# michniks2001/hunterhacks-ai-pipeline-starter architecture

> Architecture diagram of the GitHub repository michniks2001/hunterhacks-ai-pipeline-starter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/michniks2001/hunterhacks-ai-pipeline-starter
- Repository: https://github.com/michniks2001/hunterhacks-ai-pipeline-starter

## Overview

1. **Repository shape**
   - This is a two-part app: `backend/` is a FastAPI AI pipeline, and `frontend/` is a Vite + React UI.
   - The architectural boundary is clear: the backend owns all data lookup, LLM calls, validation, caching, and response shaping; the frontend only fetches JSON and renders UI.

2. **Primary user flow**
   - A user enters a neighborhood name and optional design direction in the frontend.
   - The frontend sends that request to the backend API.
   - The backend returns structured neighborhood/theme/page JSON, and the frontend converts that JSON into visible page sections.

3. **Backend orchestration layer**
   - `backend/app/main.py` and `backend/main.py` are the FastAPI entry points.
   - `backend/app/routes/theme_routes.py` exposes the API surface, including:
     - `GET /api/neighborhoods`
     - `POST /api/theme`
     - `GET /api/neighborhoods/{key}/page`
     - `POST /api/debug/cache/clear`
   - These routes likely orchestrate the pipeline rather than implementing logic directly.

4. **Neighborhood context subsystem**
   - `backend/app/services/neighborhood_service.py` and `backend/app/data/neighborhoods.json` provide curated neighborhood context.
   - Per the README, the backend first tries to match this dataset before falling back to broader context when strict matching is off.
   - This is the “verified facts” layer feeding the AI pipeline.

5. **LLM provider boundary**
   - `backend/app/services/groq_service.py` is the only place that should talk to Groq.
   - The README explicitly states Groq is called only from the backend, never the frontend.
   - This keeps API keys and model access isolated from the browser.

6. **Prompt/theme reasoning pipeline**
   - `backend/app/services/theme_resolution.py` appears to decide how user input, verified neighborhood context, and optional design direction become a theme or page plan.
   - `backend/app/services/experience_normalize.py` suggests post-processing of model output into a consistent experience structure.
   - Together, these modules represent the “AI pipeline” core: resolve intent, call the model, then normalize results.

7. **Validation, normalization, and data contracts**
   - `backend/app/models.py` likely defines the structured response types used between the route, services, and frontend.
   - The README says the backend parses model JSON, repairs common issues, and validates structure before the UI uses it.
   - This is a critical trust boundary: raw model output is not sent directly to the browser.

8. **Caching and repeatability**
   - `backend/app/cache.py` implements response caching.
   - The README emphasizes visible cache behavior: first request is fresh, later requests can be served from cache, and a debug endpoint clears it.
   - This is both a performance layer and a workshop/demo feature.

9. **Page rendering on the backend**
   - `backend/app/services/page_render.py` and `backend/app/templates/neighborhood_page.html` indicate the backend can render a neighborhood page view server-side or assemble HTML from structured data.
   - Even if the main demo is API-driven, this suggests a backend presentation path exists alongside JSON generation.

10. **Frontend rendering layer**
   - `frontend/src/App.tsx`, `frontend/src/components/DynamicNeighborhoodPage.tsx`, and `frontend/src/components/experience-blocks.tsx` are the main UI composition pieces.
   - The frontend does not generate content itself; it maps backend JSON into reusable visual blocks and page sections.

11. **Frontend API boundary**
   - `frontend/src/lib/api.ts` centralizes calls to the backend.
   - Vite configuration and the README indicate the frontend normally uses the `/api` proxy instead of hardcoding backend URLs.
   - This keeps local dev and Codespaces setup simple and avoids exposing backend implementation details in the UI.

12. **Shared UI toolkit**
   - `frontend/src/components/ui/*` is a component library layer for presentation primitives such as cards, tabs, tables, alerts, and skeleton states.
   - These components support the rendered neighborhood page but are not part of the AI pipeline itself.

13. **Runtime and deployment/dev tooling**
   - Backend: Python/FastAPI managed with `uv` (`backend/pyproject.toml`, `backend/uv.lock`).
   - Frontend: TypeScript/React managed with npm and Vite.
   - `.devcontainer/` and the setup scripts are developer-environment scaffolding; they help run both apps together but do not change the core architecture.

14. **Key architecture takeaway**
   - The system is a classic “LLM-backed content pipeline”:
     - user input enters the frontend,
     - backend enriches it with curated context,
     - Groq produces structured JSON,
     - backend validates and caches that JSON,
     - frontend renders the result into UI components.
   - The important diagram boundary is between “trusted backend orchestration” and “untrusted model output,” with validation in between.

Main entry points: [`backend/app/routes/theme_routes.py`](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/routes/theme_routes.py) (API routes), [`backend/app/services/theme_resolution.py`](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/services/theme_resolution.py) (Theme resolver), [`frontend/src/App.tsx`](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/frontend/src/App.tsx) (React app), [`backend/app/main.py`](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/main.py) (FastAPI entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_main["FastAPI entry<br/>entrypoint<br/>[main.py]"]
  node_backend_root_main["App runner<br/>entrypoint<br/>[main.py]"]
  node_theme_routes["API routes<br/>http routes<br/>[theme_routes.py]"]
  node_models["Response models<br/>contracts<br/>[models.py]"]
  node_cache[("Response cache<br/>[cache.py]")]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_neighborhood_service["Neighborhoods<br/>context service"]
  node_neighborhood_data["Neighborhood data<br/>dataset<br/>[neighborhoods.json]"]
  node_theme_resolution["Theme resolver<br/>orchestration"]
  node_groq_service["Groq client<br/>llm gateway<br/>[groq_service.py]"]
  node_experience_normalize["Normalize output<br/>postprocess"]
  node_page_render["Page renderer<br/>presentation<br/>[page_render.py]"]
  node_neighborhood_template["Page template"]
end

subgraph group_frontend["Frontend"]
  node_app["React app<br/>ui entrypoint<br/>[App.tsx]"]
  node_dynamic_page["Dynamic page<br/>ui composition"]
  node_experience_blocks["Experience blocks<br/>ui mapper"]
  node_api_client["API client<br/>http client<br/>[api.ts]"]
  node_ui_kit["UI kit<br/>components<br/>[card.tsx]"]
  node_vite_config["Vite config<br/>build config<br/>[vite.config.ts]"]
end

subgraph group_tooling["Tooling"]
  node_devcontainer["Dev container<br/>dev tooling<br/>[devcontainer.json]"]
end

node_backend_root_main -->|"starts"| node_backend_main
node_backend_main -->|"mounts"| node_theme_routes
node_theme_routes -->|"loads context"| node_neighborhood_service
node_neighborhood_service -->|"reads"| node_neighborhood_data
node_theme_routes -->|"orchestrates"| node_theme_resolution
node_theme_resolution -->|"calls model"| node_groq_service
node_theme_resolution -->|"postprocesses"| node_experience_normalize
node_experience_normalize -->|"validates"| node_models
node_theme_routes -->|"returns"| node_models
node_theme_routes -->|"stores"| node_cache
node_theme_routes -->|"renders page"| node_page_render
node_page_render -->|"uses"| node_neighborhood_template
node_app -->|"fetches"| node_api_client
node_api_client -->|"requests"| node_theme_routes
node_app -->|"composes"| node_dynamic_page
node_dynamic_page -->|"maps"| node_experience_blocks
node_experience_blocks -->|"uses"| node_ui_kit
node_vite_config -->|"proxies"| node_api_client
node_devcontainer -.->|"supports"| node_backend_main
node_devcontainer -.->|"supports"| node_app
node_config -->|"configures"| node_groq_service

click node_backend_main "https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/main.py"
click node_backend_root_main "https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/main.py"
click node_theme_routes "https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/routes/theme_routes.py"
click node_models "https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/models.py"
click node_cache "https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/cache.py"
click node_config "https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/config.py"
click node_neighborhood_service "https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/services/neighborhood_service.py"
click node_neighborhood_data "https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/data/neighborhoods.json"
click node_theme_resolution "https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/services/theme_resolution.py"
click node_groq_service "https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/services/groq_service.py"
click node_experience_normalize "https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/services/experience_normalize.py"
click node_page_render "https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/services/page_render.py"
click node_neighborhood_template "https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/templates/neighborhood_page.html"
click node_app "https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/frontend/src/App.tsx"
click node_dynamic_page "https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/frontend/src/components/DynamicNeighborhoodPage.tsx"
click node_experience_blocks "https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/frontend/src/components/experience-blocks.tsx"
click node_api_client "https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/frontend/src/lib/api.ts"
click node_ui_kit "https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/frontend/src/components/ui/card.tsx"
click node_vite_config "https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/frontend/vite.config.ts"
click node_devcontainer "https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/.devcontainer/devcontainer.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_backend_main,node_backend_root_main,node_theme_routes,node_models,node_cache,node_config,node_neighborhood_service,node_neighborhood_data,node_theme_resolution,node_groq_service,node_experience_normalize,node_page_render,node_neighborhood_template toneBlue
class node_app,node_dynamic_page,node_experience_blocks,node_api_client,node_ui_kit,node_vite_config toneAmber
class node_devcontainer toneMint
```

## Components

### Backend

FastAPI service that resolves neighborhood context, calls the model, validates output, caches responses, and renders pages.

- [FastAPI entry](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/main.py): entrypoint · ASGI startup and application wiring. · `backend/app/main.py`
- [App runner](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/main.py): entrypoint · Top-level backend launch module. · `backend/main.py`
- [API routes](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/routes/theme_routes.py): http routes · Exposes neighborhood, theme, page, and cache endpoints. · `backend/app/routes/theme_routes.py`
- [Response models](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/models.py): contracts · Structured data shapes shared across the backend pipeline and API. · `backend/app/models.py`
- [Response cache](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/cache.py): cache · Stores and clears generated responses for repeatability and speed. · `backend/app/cache.py`
- [Config](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/config.py): settings · Backend configuration and environment loading. · `backend/app/config.py`
- [Neighborhoods](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/services/neighborhood_service.py): context service · Loads curated neighborhood facts and matches user input to verified context. · `backend/app/services/neighborhood_service.py`
- [Neighborhood data](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/data/neighborhoods.json): dataset · Curated neighborhood metadata used as the trusted facts source. · `backend/app/data/neighborhoods.json`
- [Theme resolver](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/services/theme_resolution.py): orchestration · Combines user intent, neighborhood context, and design direction into a theme plan. · `backend/app/services/theme_resolution.py`
- [Groq client](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/services/groq_service.py): llm gateway · Backend-only provider boundary for model calls. · `backend/app/services/groq_service.py`
- [Normalize output](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/services/experience_normalize.py): postprocess · Repairs and standardizes model output into a consistent experience structure. · `backend/app/services/experience_normalize.py`
- [Page renderer](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/services/page_render.py): presentation · Converts structured neighborhood data into server-rendered page output. · `backend/app/services/page_render.py`
- [Page template](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/backend/app/templates/neighborhood_page.html): template · HTML template used for neighborhood page rendering. · `backend/app/templates/neighborhood_page.html`

### Frontend

Vite + React client that submits requests and renders structured neighborhood experiences.

- [React app](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/frontend/src/App.tsx): ui entrypoint · Top-level client composition and routing. · `frontend/src/App.tsx`
- [Dynamic page](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/frontend/src/components/DynamicNeighborhoodPage.tsx): ui composition · Maps backend page JSON into visible neighborhood sections. · `frontend/src/components/DynamicNeighborhoodPage.tsx`
- [Experience blocks](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/frontend/src/components/experience-blocks.tsx): ui mapper · Reusable block rendering for structured experience content. · `frontend/src/components/experience-blocks.tsx`
- [API client](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/frontend/src/lib/api.ts): http client · Central frontend boundary for calling backend endpoints. · `frontend/src/lib/api.ts`
- [UI kit](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/frontend/src/components/ui/card.tsx): components · Shared presentation primitives for cards, tabs, tables, alerts, and loading states. · `frontend/src/components/ui/card.tsx`
- [Vite config](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/frontend/vite.config.ts): build config · Frontend build and dev-server configuration, including API proxy setup. · `frontend/vite.config.ts`

### Tooling

Development environment and runtime setup for running both apps.

- [Dev container](https://github.com/michniks2001/hunterhacks-ai-pipeline-starter/blob/main/.devcontainer/devcontainer.json): dev tooling · Repository environment for local development and setup. · `.devcontainer/devcontainer.json`

## Connections

- App runner → FastAPI entry: starts · Top-level runner loads the FastAPI app.
- FastAPI entry → API routes: mounts · Application wiring registers the API routes.
- API routes → Neighborhoods: loads context · Routes consult curated neighborhood data before generation.
- Neighborhoods → Neighborhood data: reads · Service uses the curated neighborhood dataset.
- API routes → Theme resolver: orchestrates · API requests flow into the theme resolution pipeline.
- Theme resolver → Groq client: calls model · Resolver sends prompt/context to the LLM gateway.
- Theme resolver → Normalize output: postprocesses · Generated content is normalized into stable structures.
- Normalize output → Response models: validates · Normalized output is shaped to backend response contracts.
- API routes → Response models: returns · Route responses use the structured response types.
- API routes → Response cache: stores · Generated responses can be served from cache.
- API routes → Page renderer: renders page · Page endpoint can assemble backend-rendered HTML.
- Page renderer → Page template: uses · Renderer applies the HTML template.
- React app → API client: fetches · UI requests data through the centralized client.
- API client → API routes: requests · Frontend calls backend JSON endpoints.
- React app → Dynamic page: composes · Main app renders the neighborhood page experience.
- Dynamic page → Experience blocks: maps · Structured content is turned into reusable blocks.
- Experience blocks → UI kit: uses · Block rendering is built on shared UI primitives.
- Vite config → API client: proxies · Development setup routes API traffic to the backend.
- Dev container → FastAPI entry: supports · Environment scaffolding helps run the backend locally.
- Dev container → React app: supports · Environment scaffolding helps run the frontend locally.
- Config → Groq client: configures · Backend config supplies service settings and secrets.