# Documentation Index ## Quick Start ```bash # 1. Install dependencies uv sync # 2. Configure AWS credentials cp .env.example .env && vim .env # set AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY # 3. Generate a project uv run python main.py generate --prompt "A warehouse management system" ``` The generated project lands at `runs/outputs/_/`. --- ## All Documentation Files | File | Description | |------|-------------| | [README.md](README.md) | Project overview, tech stack, setup, folder structure | | [ARCHITECTURE.md](ARCHITECTURE.md) | System design, layer communication map, error strategy, env vars | | [API.md](API.md) | Every Bedrock LLM call — model, request shape, response, error path | | [SERVICES.md](SERVICES.md) | Every service function with step-by-step input/output/error trace | | [COMPONENTS.md](COMPONENTS.md) | Each pipeline step documented as a component (input/process/output/error) | | [STATE.md](STATE.md) | All data contracts and state shapes: when created, mutated, consumed | | [DATA_FLOW.md](DATA_FLOW.md) | 5 key end-to-end flows traced step-by-step with full type annotations | | [flowcharts/data-pipeline.md](flowcharts/data-pipeline.md) | Left-to-right Mermaid diagram of the full data pipeline | | [flowcharts/api-request-lifecycle.md](flowcharts/api-request-lifecycle.md) | Sequence diagrams: service → Bedrock → response (both client paths) | | [flowcharts/auth-flow.md](flowcharts/auth-flow.md) | AWS credential resolution + Bedrock IAM authorization | | [flowcharts/generate-flow.md](flowcharts/generate-flow.md) | Full `generate` command flow with per-step artifacts | | [flowcharts/state-flow.md](flowcharts/state-flow.md) | State transitions for all data contracts and RunLog | --- ## Where to Find X | I want to understand... | File to read | |-------------------------|-------------| | What a function takes as input | [SERVICES.md](SERVICES.md) — INPUT section of each step block | | What a function returns | [SERVICES.md](SERVICES.md) — OUTPUT section of each step block | | Where a return value goes next | [DATA_FLOW.md](DATA_FLOW.md) — OUTPUT → "to:" field | | Full trace of the generate command | [DATA_FLOW.md](DATA_FLOW.md) — FLOW 1 | | Full trace of a Bedrock LLM call | [DATA_FLOW.md](DATA_FLOW.md) — FLOW 2 | | How RunLog telemetry accumulates | [DATA_FLOW.md](DATA_FLOW.md) — FLOW 3 | | What a Bedrock API call sends/receives | [API.md](API.md) | | Which model is used in which step | [ARCHITECTURE.md](ARCHITECTURE.md) — Routing Strategy table | | What environment variables exist | [ARCHITECTURE.md](ARCHITECTURE.md) — Environment Variables table | | The shape of IngestedInputs | [STATE.md](STATE.md) — STATE: IngestedInputs | | The shape of LoadedPRD | [STATE.md](STATE.md) — STATE: LoadedPRD | | The shape of api_manifest | [STATE.md](STATE.md) — STATE: api_manifest | | The shape of AppPlan | [STATE.md](STATE.md) — STATE: AppPlan | | The 12 sections of IRBundle | [STATE.md](STATE.md) — STATE: IRBundle | | The shape of MultiPageBundle | [STATE.md](STATE.md) — STATE: MultiPageBundle | | What props/params each step takes | [COMPONENTS.md](COMPONENTS.md) | | How state changes propagate | [flowcharts/state-flow.md](flowcharts/state-flow.md) | | End-to-end request lifecycle | [flowcharts/api-request-lifecycle.md](flowcharts/api-request-lifecycle.md) | | Full generate flow with artifacts | [flowcharts/generate-flow.md](flowcharts/generate-flow.md) | | How AWS auth works | [flowcharts/auth-flow.md](flowcharts/auth-flow.md) | | The full data pipeline left to right | [flowcharts/data-pipeline.md](flowcharts/data-pipeline.md) | | How errors propagate | [ARCHITECTURE.md](ARCHITECTURE.md) — Error Handling Strategy | | What files each step writes to disk | [COMPONENTS.md](COMPONENTS.md) — Artifacts written section | | How LLM tokens are tracked | [API.md](API.md) — Token Usage Tracking section | --- ## Key Data Contracts at a Glance ``` ingest() → IngestedInputs { user_prompt, images_dir, image_paths } │ generate_from_prompt() │ (prompt mode) generate_prd() │ (image mode) → LoadedPRD { path, text, images, ddl_path } │ generate_backend() │ → api_manifest: dict { version, modules[{name, prefix, endpoints}], enums } → backend/ (FastAPI project files on disk) │ generate_app_ir() │ ├── detect_pages() → AppPlan { app_name, pages[PageNode], default_route, design_system } └── generate_ir_bundle_for_page() × N │ → AppIRBundle { app_plan, ir_pages[IRPage], run_id, encoded_images } │ generate_react_pages() │ ├── generate_page_react_code() × N │ ├── generate_router_code() │ └── generate_context_code() │ → MultiPageBundle { app_plan, pages[PageBundle], router_code, context_code } │ write_generated_files() │ → frontend/src/ (TSX files on disk) ``` --- ## Bedrock Model Reference | Step | Model family | Default model ID | Purpose | |------|-------------|-----------------|---------| | 02 PRD + DDL | Sonnet | `claude-3-5-sonnet-20241022-v2:0` | Text + SQL generation | | 03 Backend | Sonnet | `claude-3-5-sonnet-20241022-v2:0` | Python code generation | | 04a Page detection | Opus | `global.anthropic.claude-opus-4-6-v1` | Vision + structural decision | | 04b IR generation | Opus | `global.anthropic.claude-opus-4-6-v1` | Complex 12-section JSON schema | | 05 React TSX | Sonnet | `global.anthropic.claude-sonnet-4-5-20250929-v1:0` | Long TSX file generation | Override any model via environment variable — see [ARCHITECTURE.md#environment-variables](ARCHITECTURE.md#environment-variables). --- ## Scan Summary ``` TECH STACK: python 3.10+ | runtime boto3 ≥1.42 | AWS Bedrock SDK (direct invoke_model) langchain-aws ≥1.3 | ChatBedrockConverse wrapper anthropic[bedrock] | Anthropic SDK (edit pipeline, currently disabled) pydantic ≥2.12 | schema validation for all IR structures pymupdf | PDF text + image extraction python-pptx | PPTX text + image extraction python-docx | DOCX text + image extraction python-dotenv | .env loading at startup redis[hiredis] | optional session cache (edit pipeline) openai ≥2.34 | alternative LLM client (some sub-steps) jsonschema | JSON schema validation uv | package manager + virtual environment ENTRY POINTS: main.py generate | CLI: full pipeline orchestrator.generate_project() | programmatic API PIPELINE STEPS: step-01-input-ingestion | ingest() → IngestedInputs step-02-prd-generation | generate_from_prompt() | generate_prd() → LoadedPRD step-02c-dalfin | Mantara + Dalfin JSON (optional, non-fatal on failure) step-03-backend-generation | Orchestrator.run() → api_manifest + FastAPI project step-04-ir-generation | generate_app_ir() → AppIRBundle step-05-react-generation | generate_react_pages() + scaffold_frontend() → MultiPageBundle + frontend/src/ SHARED UTILITIES: shared/config.py | single source of truth: paths, model IDs, timeouts shared/run_artifacts.py | new_run_id(), step_output_dir() shared/run_log.py | RunLog, StepEvent, LLMCall — telemetry shared/llm_logging.py | timed_llm_call() context manager shared/timing.py | log_timed_step() context manager shared/extractors.py | extract_json_object(), extract_code_block() shared/media/images.py | EncodedImage, encode_image() shared/media/prd_loader.py | LoadedPRD, validate_and_load_prd() SCHEMAS (pydantic): shared/schemas/ir_bundle.py | IRBundle — 12 sections (the core UI spec) shared/schemas/app_plan.py | AppPlan, PageNode, DesignSystem shared/schemas/app_ir.py | AppIRBundle, IRPage, MultiPageModelConfig shared/schemas/multi_page_bundle.py | MultiPageBundle, PageBundle shared/schemas/plan.py | ExecutionPlan, PlanStep LLM CLIENTS: shared/bedrock_client.py | build_chat_model() → ChatBedrockConverse (LangChain) shared/bedrock_raw_client.py | create_llm_client() → BedrockLLMClient (boto3 direct) shared/anthropic_client.py | build_bedrock_client() → AnthropicBedrock (edit only) ```