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

README.md

@@ -1,6 +1,8 @@
 # foundary-test-1770784989
 
-Foundary Studio: Conversational product development
+A product studio for conversational product development. Build, iterate, and ship products through natural conversation — from idea to deployed software in a single workflow.
+
+Foundary Studio combines Go backend services, TypeScript frontends, and shared libraries in a polyglot monorepo, orchestrated by AI-assisted development tooling that turns conversations into working code.
 
 ## Quickstart
 
@@ -12,21 +14,38 @@ cd foundary-test-1770784989
 # Install dependencies
 ./scripts/install.sh
 
-# Start local development
+# Start local development (PostgreSQL, Redis, all services)
 ./scripts/dev.sh
 ```
 
-## Project Structure
+## Architecture
 
 ```
 foundary-test-1770784989/
-├── services/     # Go API services
+├── services/     # Go API services (port 8001+)
-├── workers/      # Background workers
+├── workers/      # Go background workers
-├── apps/         # Frontend applications
+├── apps/         # TypeScript frontends (port 3001+)
-├── cli/          # CLI tools
+├── cli/          # Go CLI tools
 ├── packages/     # Shared TypeScript packages
+│   ├── ui/       # Headless UI component library
+│   ├── layout/   # Dashboard shell and navigation
+│   ├── auth/     # Auth provider and protected routes
+│   ├── api-client/ # Generated typed API client
+│   └── logger/   # Structured HTTP/console logging
 ├── pkg/          # Shared Go packages
-└── scripts/      # Development scripts
+│   ├── app/      # Service bootstrapper (Wrap, Bind, Health)
+│   ├── auth/     # JWT and API key authentication
+│   ├── config/   # Environment-based configuration
+│   ├── database/ # PostgreSQL connections and migrations
+│   ├── httperror/ # Typed HTTP error responses
+│   ├── httpresponse/ # Standard response envelope
+│   ├── middleware/ # CORS, request ID, recovery, logging
+│   ├── openapi/  # OpenAPI 3.0 spec builder + docs UI
+│   ├── queue/    # Redis-backed job queue
+│   ├── realtime/ # WebSocket hub with Redis pub/sub
+│   └── svc/      # Service-to-service discovery
+├── scripts/      # Development and CI scripts
+└── docs/         # Generated API documentation
 ```
 
 ## Scripts
@@ -35,29 +54,28 @@ foundary-test-1770784989/
 |--------|-------------|
 | `./scripts/dev.sh` | Start local development environment |
 | `./scripts/install.sh` | Install all dependencies |
-| `./scripts/quality.sh` | Run quality checks on all components |
+| `./scripts/quality.sh` | Run linting, tests, and quality checks |
 | `./scripts/discover.sh` | List all components in the monorepo |
+| `./scripts/generate-client.sh` | Generate TypeScript API client from OpenAPI specs |
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| Backend | Go 1.25, chi router, sqlx, PostgreSQL, Redis |
+| Frontend | TypeScript, React, Radix UI, Tailwind CSS |
+| Package management | pnpm workspaces (TS), Go workspaces (Go) |
+| Infrastructure | Docker Compose (local), Woodpecker CI/CD |
+| Auth | JWT + API key with opt-in middleware |
+| Docs | OpenAPI 3.0 specs with Scalar UI |
 
 ## API Documentation
 
-API documentation is automatically generated from OpenAPI specs and deployed to:
+API documentation is generated from OpenAPI specs and deployed to:
 
 - **Docs**: https://docs.9d4u7q6t.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