build: Set up the monorepo workspace. Ensure the root README describes a pro...

README.md

@@ -1,6 +1,6 @@
-# foundary-test-1770773605
+# Foundary Studio
 
-Foundary Studio: Conversational product development
+A product studio for conversational product development. Foundary Studio enables teams to build, iterate on, and ship products through natural conversation — turning dialogue into working software.
 
 ## Quickstart
 
@@ -12,55 +12,82 @@ cd foundary-test-1770773605
 # Install dependencies
 ./scripts/install.sh
 
-# Start local development
+# Start local development (PostgreSQL, Redis, all services)
 ./scripts/dev.sh
 ```
 
-## Project Structure
+## Architecture
+
+Foundary Studio is a monorepo with Go backend services, TypeScript frontend applications, and shared packages for both.
 
 ```
 foundary-test-1770773605/
-├── services/     # Go API services
-├── workers/      # Background workers
-├── apps/         # Frontend applications
-├── cli/          # CLI tools
-├── packages/     # Shared TypeScript packages
-├── pkg/          # Shared Go packages
-└── scripts/      # Development scripts
+├── services/       # Go API services (port 8001+)
+├── workers/        # Go background workers (queue consumers, jobs)
+├── apps/           # TypeScript frontend applications (port 3001+)
+├── cli/            # Go CLI tools
+├── packages/       # Shared TypeScript packages
+│   ├── ui/         # Component library (Radix + CSS variables)
+│   ├── layout/     # Dashboard layout
+│   ├── auth/       # Authentication provider
+│   ├── api-client/ # Generated TypeScript API client
+│   └── logger/     # HTTP and console logging
+├── pkg/            # Shared Go packages
+│   ├── app/        # Service bootstrapper
+│   ├── auth/       # JWT and API key authentication
+│   ├── config/     # Configuration management
+│   ├── database/   # Database utilities
+│   ├── httpclient/ # Resilient HTTP client (circuit breaker, retries)
+│   ├── httperror/  # Typed HTTP errors
+│   ├── httpresponse/ # Response envelope ({data, meta})
+│   ├── logging/    # Structured logging (slog)
+│   ├── middleware/  # HTTP middleware (CORS, recovery, request ID)
+│   ├── openapi/    # OpenAPI 3.0 spec builder + Scalar docs
+│   ├── queue/      # PostgreSQL-backed job queue
+│   ├── realtime/   # WebSocket and Redis pub/sub
+│   └── svc/        # Inter-service discovery and communication
+├── scripts/        # Development and CI scripts
+└── docs/           # API documentation
 ```
 
-## Scripts
+### Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| Backend services | Go, Chi router, PostgreSQL, Redis |
+| Frontend apps | TypeScript, React |
+| Shared UI | Radix primitives, CSS custom properties |
+| Job processing | PostgreSQL-backed queue |
+| Real-time | WebSocket, Redis pub/sub |
+| Workspace | Go workspaces, pnpm workspaces |
+| Infrastructure | Docker Compose (local), Woodpecker CI |
+
+## Development
+
+### Scripts
 
 | Script | Description |
 |--------|-------------|
-| `./scripts/dev.sh` | Start local development environment |
-| `./scripts/install.sh` | Install all dependencies |
-| `./scripts/quality.sh` | Run quality checks on all components |
+| `./scripts/dev.sh` | Start local dev environment (Docker services + all components) |
+| `./scripts/install.sh` | Install all dependencies (pnpm packages + Go modules) |
+| `./scripts/quality.sh` | Run quality checks (lint, test, typecheck) |
 | `./scripts/discover.sh` | List all components in the monorepo |
+| `./scripts/generate-client.sh` | Generate TypeScript API client from OpenAPI specs |
 
-## API Documentation
+### Local Infrastructure
 
-API documentation is automatically generated from OpenAPI specs and deployed to:
+Local development uses Docker Compose for backing services:
+
+- **PostgreSQL 16** on port 5432 (user: `dev`, database: `foundary-test-1770773605`)
+- **Redis 7** on port 6379
+
+### API Documentation
+
+Each service exposes an OpenAPI spec at `/openapi.json`. Documentation is generated and deployed automatically on push to `main`.
 
 - **Docs**: https://docs.dfq64dsk.threesix.ai
-- **OpenAPI Spec**: Each service exposes `/openapi.json`
 
-To regenerate docs locally:
-
-```bash
-# Start services locally
-./scripts/dev.sh
-
-# Generate Slate markdown from OpenAPI specs
-./docs/scripts/generate-docs.sh http://localhost
-
-# Preview docs (optional - requires Ruby)
-cd docs && bundle install && bundle exec middleman serve
-```
-
-Documentation is automatically rebuilt on every push to `main`.
-
-## Adding Components
+### Adding Components
 
 Components are added via the rdev API:
 
@@ -68,10 +95,10 @@ Components are added via the rdev API:
 # Add a Go service
 curl -X POST $RDEV_API_URL/projects/foundary-test-1770773605/components \
   -H "X-API-Key: $RDEV_API_KEY" \
-  -d '{"type": "service", "name": "auth-api"}'
+  -d '{"type": "service", "name": "my-service"}'
 
 # Add a React app
 curl -X POST $RDEV_API_URL/projects/foundary-test-1770773605/components \
   -H "X-API-Key: $RDEV_API_KEY" \
-  -d '{"type": "app", "name": "dashboard", "template": "app-react"}'
+  -d '{"type": "app", "name": "my-app", "template": "app-react"}'
 ```