docs: add architecture, deployment guides and update dev environment docs

Co-Authored-By: Paperclip <noreply@paperclip.ing>

docs/dev-environment.md

@@ -2,8 +2,9 @@
 
 ## Prerequisites
 
-- Docker Engine 24+ & Docker Compose v2
-- Node.js 22 LTS (for running app services locally)
+- **Docker Engine 24+** & Docker Compose v2
+- **Node.js 22 LTS**
+- **pnpm 10.27+** — install via `corepack enable && corepack prepare pnpm@latest --activate`
 
 ## Quick Start
 
@@ -16,19 +17,41 @@ docker compose up -d
 
 # 3. Verify all services are healthy
 docker compose ps
+
+# 4. Install dependencies
+pnpm install
+
+# 5. Generate Prisma client
+pnpm db:generate
+
+# 6. Run database migrations
+pnpm db:migrate:dev
+
+# 7. Seed the database (optional)
+pnpm db:seed
+
+# 8. Start API and Web in dev mode
+pnpm dev
 ```
 
-## Services
+API runs at `http://localhost:3000`, Web at `http://localhost:3001`.
 
-| Service    | Port(s)     | Description                  | Dashboard/UI                    |
-| ---------- | ----------- | ---------------------------- | ------------------------------- |
-| PostgreSQL | 5432        | Database with PostGIS        | —                               |
-| Redis      | 6379        | Cache, sessions, queue       | —                               |
-| Typesense  | 8108        | Full-text search engine      | http://localhost:8108/health    |
-| MinIO      | 9000 / 9001 | S3-compatible object storage | http://localhost:9001 (console) |
+## Infrastructure Services
+
+| Service | Port(s) | Description | Dashboard/UI |
+|---------|---------|-------------|--------------|
+| PostgreSQL + PostGIS | 5432 | Database with spatial queries | — |
+| Redis | 6379 | Cache, sessions, queue | — |
+| Typesense | 8108 | Full-text search engine | `http://localhost:8108/health` |
+| MinIO | 9000 / 9001 | S3-compatible object storage | `http://localhost:9001` (console) |
+| AI Services | 8000 | FastAPI — AVM + moderation | `http://localhost:8000/health` |
+| Prometheus | 9090 | Metrics collection | `http://localhost:9090` |
+| Grafana | 3002 | Dashboards & monitoring | `http://localhost:3002` |
 
 ## Common Commands
 
+### Docker Compose
+
 ```bash
 # Start services
 docker compose up -d
@@ -50,6 +73,36 @@ docker compose restart redis
 docker compose ps
 ```
 
+### Development
+
+```bash
+pnpm dev              # Start all apps in watch mode
+pnpm build            # Build all packages
+pnpm lint             # ESLint across monorepo
+pnpm typecheck        # TypeScript type checking
+pnpm format           # Prettier formatting
+pnpm test             # Run unit/integration tests
+```
+
+### Database
+
+```bash
+pnpm db:generate      # Regenerate Prisma client
+pnpm db:migrate:dev   # Create and apply migrations
+pnpm db:seed          # Seed database
+pnpm db:studio        # Open Prisma Studio (visual editor)
+pnpm db:reset         # Reset database (destructive)
+```
+
+### E2E Testing
+
+```bash
+pnpm test:e2e         # Run all E2E tests
+pnpm test:e2e:api     # API tests only
+pnpm test:e2e:web     # Web UI tests only
+pnpm test:e2e:report  # Open HTML test report
+```
+
 ## Connecting to Services
 
 ### PostgreSQL
@@ -76,11 +129,25 @@ curl http://localhost:8108/health
 
 ### MinIO
 
-- API: `http://localhost:9000`
-- Console: `http://localhost:9001` (login: minioadmin / minioadmin_secret)
+- **API**: `http://localhost:9000`
+- **Console**: `http://localhost:9001` (login: `minioadmin` / `minioadmin_secret`)
+
+### AI Services
+
+```bash
+curl http://localhost:8000/health
+```
+
+### Grafana
+
+- **URL**: `http://localhost:3002`
+- **Login**: `admin` / `admin` (default, configurable via `.env`)
 
 ## Troubleshooting
 
-- **Port conflict**: Change ports in `.env` (e.g., `DB_PORT=5433`)
-- **Permission issues**: Run `docker compose down -v` and restart
-- **PostGIS not available**: Ensure using `postgis/postgis:16-3.4` image
+- **Port conflict** — Change ports in `.env` (e.g., `DB_PORT=5433`)
+- **Permission issues** — Run `docker compose down -v` and restart
+- **PostGIS not available** — Ensure using `postgis/postgis:16-3.4` image
+- **Prisma client out of date** — Run `pnpm db:generate` after pulling schema changes
+- **AI service not starting** — Check `docker compose logs ai-services` for Python dependency errors
+- **Typesense unhealthy** — Verify `TYPESENSE_API_KEY` matches in `.env` and Docker config