Full-Stack AI Product Scaffold

This repository is structured as a full-stack scaffold with a shared project workspace:

• backend/: FastAPI + LangGraph runtime, auth, persistence, and observability
• frontend/: reserved frontend workspace for the product UI
• workspace/: shared context, PRD, execution board, design system, and feature execution docs

The backend is runnable today. The frontend is intentionally left framework-neutral so you can drop in the UI stack you want for the next project.

The backend now exposes a neutral thread + runtime contract, with the original chat routes preserved as a compatibility adapter.

Repository Layout

backend/    # API runtime, Docker stack, tests, observability configs
frontend/   # frontend app workspace placeholder
workspace/  # shared project docs for backend + frontend work

Shared Workspace Documents

Project knowledge should stay in the shared workspace rather than being duplicated per layer:

• workspace/context.md: project context, terminology, and architecture boundaries
• workspace/prd.md: project-level product source of truth
• workspace/execution.md: project-level feature queue, dependency board, and implementation readiness tracker
• workspace/design.md: global design rules for future frontend work
• workspace/features/<feature-slug>.md: one feature's execution document

Quick Start

Install the backend dependencies:

make install

Create the backend development env file:

cp backend/.env.example backend/.env.development

Fill in the required backend values:

OPENAI_API_KEY=...
JWT_SECRET_KEY=...

Start the default full stack:

make docker-compose-up ENV=development

Or run the backend locally with Docker Postgres:

cd backend
docker compose --env-file .env.development up -d db
cd ..
make dev

Default Platform Stack

The default backend Docker stack includes:

• FastAPI app
• PostgreSQL with pgvector image
• Prometheus
• Grafana
• Loki
• Promtail

Optional host metrics are available through:

make docker-compose-observability-up ENV=development

Where To Work

• backend runtime changes: start in backend/
• frontend product UI changes: start in frontend/
• product definition, design, and feature execution: start in workspace/

Notes

• Root make commands proxy into backend/
• The frontend directory is intentionally minimal until you pick a concrete UI stack
• The backend runtime is message-oriented internally, but the public API is no longer chat-only
• Use relative paths when extending repo documentation so the scaffold stays portable