How michniks2001/hunterhacks-ai-pipeline-starter works
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: theme_routes.py API routes · theme_resolution.py Theme resolver · App.tsx React app · main.py FastAPI entry
Components 20
Backend
FastAPI service that resolves neighborhood context, calls the model, validates output, caches responses, and renders pages.
- FastAPI entry · ASGI startup and application wiring.
backend/app/main.py - App runner · Top-level backend launch module.
backend/main.py - API routes · Exposes neighborhood, theme, page, and cache endpoints.
backend/app/routes/theme_routes.py - Response models · Structured data shapes shared across the backend pipeline and API.
backend/app/models.py - Response cache · Stores and clears generated responses for repeatability and speed.
backend/app/cache.py - Config · Backend configuration and environment loading.
backend/app/config.py - Neighborhoods · Loads curated neighborhood facts and matches user input to verified context.
backend/app/services/neighborhood_service.py - Neighborhood data · Curated neighborhood metadata used as the trusted facts source.
backend/app/data/neighborhoods.json - Theme resolver · Combines user intent, neighborhood context, and design direction into a theme plan.
backend/app/services/theme_resolution.py - Groq client · Backend-only provider boundary for model calls.
backend/app/services/groq_service.py - Normalize output · Repairs and standardizes model output into a consistent experience structure.
backend/app/services/experience_normalize.py - Page renderer · Converts structured neighborhood data into server-rendered page output.
backend/app/services/page_render.py - Page 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 · Top-level client composition and routing.
frontend/src/App.tsx - Dynamic page · Maps backend page JSON into visible neighborhood sections.
frontend/src/components/DynamicNeighborhoodPage.tsx - Experience blocks · Reusable block rendering for structured experience content.
frontend/src/components/experience-blocks.tsx - API client · Central frontend boundary for calling backend endpoints.
frontend/src/lib/api.ts - UI kit · Shared presentation primitives for cards, tabs, tables, alerts, and loading states.
frontend/src/components/ui/card.tsx - Vite 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 · Repository environment for local development and setup.
.devcontainer/devcontainer.json
Connections 21
- 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.