# talelboussetta/hackfarm architecture

> Architecture diagram of the GitHub repository talelboussetta/hackfarm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/talelboussetta/hackfarm
- Repository: https://github.com/talelboussetta/hackfarm

## Overview

1. **What this repo is**
   HackFarmer is a two-tier product: a React/Vite frontend for submitting and monitoring generation jobs, and a FastAPI/Python backend that turns a brief into a generated project by running a multi-agent workflow.

2. **Primary user-facing flow**
   A user submits a project brief as text or uploads a PDF/DOCX. The backend normalizes that input, creates a job, then drives the generation pipeline. The frontend listens to live updates, shows agent progress, and later lets the user browse, preview, refine, or download the generated codebase.

3. **Frontend boundary**
   The frontend is a dashboard-style SPA with pages for landing, home, job detail, history, settings, admin, and per-agent stage views. Its key responsibilities are authentication, job submission, streaming progress, rendering the pipeline graph, and displaying generated artifacts such as code views and refinement panels.

4. **Frontend data access**
   Frontend code is organized around a thin API layer and a few domain hooks: `useAuth`, `useJobSubmit`, and `useJobStream`. These hook into backend endpoints and Appwrite client configuration, keeping UI components mostly presentation-focused. The frontend also includes themed agent UI, animations, and code preview components that reflect the backend’s current stage.

5. **Backend API boundary**
   The FastAPI backend exposes the system surface area through routes for auth, jobs, streaming, downloads, settings, and admin. This is the main boundary between client and orchestration logic: the frontend never talks directly to agents, only to API endpoints and stream channels.

6. **Job orchestration core**
   The central backend subsystem is the agent pipeline under `backend/src/agents`. The agents are specialized by role: analyst, architect, frontend, backend, business, integrator, validator, GitHub publisher, plus graph/state/refinement helpers. The README’s pipeline shows a staged loop: analyze → architect → generate parallel outputs → integrate → validate → optionally refine → publish.

7. **LLM and prompt layer**
   The backend’s `llm` package contains a router and prompt files for the different agents. This suggests model/provider abstraction rather than a single hardcoded model. In architecture terms, the agent layer is separated from provider specifics, so model selection and prompt behavior can change without altering the pipeline structure.

8. **Input preparation and document ingestion**
   The `ingestion` package handles converting raw user input into a normalized brief. PDF and DOCX parsers feed a normalizer, which likely produces a common textual representation for downstream agents. This is the boundary where user-provided documents become structured agent input.

9. **External integrations**
   The repo integrates with Appwrite and GitHub, with optional n8n automation support. Appwrite is used for authentication and user-scoped data, and likely also for persistence/realtime features. GitHub is the final publishing target for generated repos, while n8n appears to be an auxiliary automation bridge rather than a core dependency.

10. **Security and per-user secrets**
    User provider keys are managed server-side in `core/encryption.py` and `core/key_manager.py`, indicating encrypted storage of API keys rather than exposing them to the browser. This is an important architectural boundary: the frontend collects configuration, but sensitive values are encrypted and handled by backend services only.

11. **Runtime services and generated artifacts**
    The backend includes queue, event, and zip-building utilities, which point to asynchronous job execution, status broadcasting, and packaging of outputs for download. The `downloads` route and `zip_builder` suggest the system can produce exportable bundles even before or alongside GitHub publishing.

12. **Deployment shape**
    The repo is containerized with separate frontend and backend Dockerfiles, plus local and production compose files. CI/CD is automated through GitHub Actions, and deployment scripts/configs reference Appwrite setup and backend checks. The architecture is therefore designed for split deployment, with the frontend serving the UI and the backend running long-lived generation jobs.

13. **Test and operational boundaries**
    There are backend-focused tests for end-to-end behavior, security, and specific pipeline phases. Documentation also includes API reference, event types, agent contracts, and deployment notes, which indicates the system’s most important contracts are the job lifecycle, streaming events, and agent outputs rather than a large set of independent services.

14. **How to draw the main diagram**
    The cleanest architecture diagram would show: user/browser → frontend SPA → backend FastAPI API/stream endpoints → orchestration layer (agents + LLM router) → integrations (Appwrite, GitHub, optional n8n) → generated artifacts/downloads. The data path should emphasize the job loop and validation/refinement cycle, because that is the core behavior of the system.

Main entry points: [`backend/src/api/main.py`](https://github.com/talelboussetta/hackfarm/blob/main/backend/src/api/main.py) (FastAPI API), [`backend/src/agents/__init__.py`](https://github.com/talelboussetta/hackfarm/blob/main/backend/src/agents/__init__.py) (Agent Pipeline), [`backend/src/integrations/github.py`](https://github.com/talelboussetta/hackfarm/blob/main/backend/src/integrations/github.py) (Integrations), [`frontend/src/App.jsx`](https://github.com/talelboussetta/hackfarm/blob/main/frontend/src/App.jsx) (SPA)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_spa["SPA<br/>react app<br/>[App.jsx]"]
  node_ui["Job UI<br/>views<br/>[Job.jsx]"]
  node_hooks["Data Hooks<br/>client data<br/>[useJobStream.js]"]
end

subgraph group_backend["Backend"]
  node_api["FastAPI API<br/>http boundary<br/>[main.py]"]
  node_auth_routes["Auth<br/>api routes<br/>[auth.py]"]
  node_job_routes["Jobs<br/>api routes<br/>[jobs.py]"]
  node_stream_routes["Stream<br/>api routes<br/>[stream.py]"]
  node_support_routes["Admin & exports<br/>api routes<br/>[downloads.py]"]
  node_ingestion["Ingestion<br/>input prep<br/>[normalizer.py]"]
  node_orchestrator{{"Agent Pipeline<br/>workflow engine<br/>[__init__.py]"}}
  node_agents["Agents<br/>specialized roles<br/>[analyst.py]"]
  node_llm["LLM Layer<br/>model router<br/>[router.py]"]
  node_runtime["Runtime Core<br/>job services<br/>[queue_manager.py]"]
  node_integrations["Integrations<br/>external adapters<br/>[github.py]"]
  node_artifacts[("Artifacts<br/>generated output<br/>[zip_builder.py]")]
end

subgraph group_external["External services"]
  node_browser(("User<br/>client"))
  node_appwrite[("Appwrite<br/>external auth/data<br/>[appwrite_client.py]")]
  node_github[("GitHub<br/>publish target<br/>[github.py]")]
  node_n8n[("n8n<br/>automation bridge<br/>[n8n.py]")]
end

node_browser -->|"use"| node_spa
node_spa -->|"data"| node_hooks
node_spa -->|"render"| node_ui
node_hooks -->|"call"| node_api
node_hooks -->|"auth"| node_appwrite
node_api -->|"mount"| node_auth_routes
node_api -->|"mount"| node_job_routes
node_api -->|"mount"| node_stream_routes
node_api -->|"mount"| node_support_routes
node_job_routes -->|"normalize"| node_ingestion
node_job_routes -->|"start"| node_orchestrator
node_ingestion -->|"input"| node_orchestrator
node_orchestrator -->|"coordinate"| node_agents
node_agents -->|"prompt"| node_llm
node_orchestrator -->|"events"| node_runtime
node_runtime -->|"build"| node_artifacts
node_integrations -->|"sync"| node_appwrite
node_integrations -->|"publish"| node_github
node_integrations -.->|"optional"| node_n8n
node_orchestrator -->|"handoff"| node_integrations
node_stream_routes -->|"broadcast"| node_runtime
node_support_routes -->|"download"| node_artifacts

click node_spa "https://github.com/talelboussetta/hackfarm/blob/main/frontend/src/App.jsx"
click node_ui "https://github.com/talelboussetta/hackfarm/blob/main/frontend/src/pages/Job.jsx"
click node_hooks "https://github.com/talelboussetta/hackfarm/blob/main/frontend/src/hooks/useJobStream.js"
click node_api "https://github.com/talelboussetta/hackfarm/blob/main/backend/src/api/main.py"
click node_auth_routes "https://github.com/talelboussetta/hackfarm/blob/main/backend/src/api/routes/auth.py"
click node_job_routes "https://github.com/talelboussetta/hackfarm/blob/main/backend/src/api/routes/jobs.py"
click node_stream_routes "https://github.com/talelboussetta/hackfarm/blob/main/backend/src/api/routes/stream.py"
click node_support_routes "https://github.com/talelboussetta/hackfarm/blob/main/backend/src/api/routes/downloads.py"
click node_ingestion "https://github.com/talelboussetta/hackfarm/blob/main/backend/src/ingestion/normalizer.py"
click node_orchestrator "https://github.com/talelboussetta/hackfarm/blob/main/backend/src/agents/__init__.py"
click node_agents "https://github.com/talelboussetta/hackfarm/blob/main/backend/src/agents/analyst.py"
click node_llm "https://github.com/talelboussetta/hackfarm/blob/main/backend/src/llm/router.py"
click node_runtime "https://github.com/talelboussetta/hackfarm/blob/main/backend/src/core/queue_manager.py"
click node_integrations "https://github.com/talelboussetta/hackfarm/blob/main/backend/src/integrations/github.py"
click node_appwrite "https://github.com/talelboussetta/hackfarm/blob/main/backend/src/appwrite_client.py"
click node_github "https://github.com/talelboussetta/hackfarm/blob/main/backend/src/integrations/github.py"
click node_n8n "https://github.com/talelboussetta/hackfarm/blob/main/backend/src/integrations/n8n.py"
click node_artifacts "https://github.com/talelboussetta/hackfarm/blob/main/backend/src/core/zip_builder.py"

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_spa,node_ui,node_hooks toneBlue
class node_api,node_auth_routes,node_job_routes,node_stream_routes,node_support_routes,node_ingestion,node_orchestrator,node_agents,node_llm,node_runtime,node_integrations,node_artifacts toneAmber
class node_browser,node_appwrite,node_github,node_n8n toneMint
```

## Components

### Frontend

React/Vite SPA and its presentation/data-access layers.

- [SPA](https://github.com/talelboussetta/hackfarm/blob/main/frontend/src/App.jsx): react app · Main React/Vite application shell and routed pages. · `frontend/src/App.jsx`
- [Job UI](https://github.com/talelboussetta/hackfarm/blob/main/frontend/src/pages/Job.jsx): views · Dashboard pages and generation-focused UI components. · `frontend/src/pages/Job.jsx`
- [Data Hooks](https://github.com/talelboussetta/hackfarm/blob/main/frontend/src/hooks/useJobStream.js): client data · Thin auth, submit, and streaming hooks plus API/Appwrite clients. · `frontend/src/hooks/useJobStream.js`

### Backend

FastAPI API surface plus orchestration and runtime services.

- [FastAPI API](https://github.com/talelboussetta/hackfarm/blob/main/backend/src/api/main.py): http boundary · Backend application entry and API route assembly. · `backend/src/api/main.py`
- [Auth](https://github.com/talelboussetta/hackfarm/blob/main/backend/src/api/routes/auth.py): api routes · Authentication and session endpoints. · `backend/src/api/routes/auth.py`
- [Jobs](https://github.com/talelboussetta/hackfarm/blob/main/backend/src/api/routes/jobs.py): api routes · Job creation, control, and status endpoints. · `backend/src/api/routes/jobs.py`
- [Stream](https://github.com/talelboussetta/hackfarm/blob/main/backend/src/api/routes/stream.py): api routes · Live progress/event streaming endpoints. · `backend/src/api/routes/stream.py`
- [Admin & exports](https://github.com/talelboussetta/hackfarm/blob/main/backend/src/api/routes/downloads.py): api routes · Settings, admin, and download endpoints. · `backend/src/api/routes/downloads.py`
- [Ingestion](https://github.com/talelboussetta/hackfarm/blob/main/backend/src/ingestion/normalizer.py): input prep · Parsers and normalizer that turn uploaded documents into a brief. · `backend/src/ingestion/normalizer.py`
- [Agent Pipeline](https://github.com/talelboussetta/hackfarm/blob/main/backend/src/agents/__init__.py): workflow engine · Central multi-agent generation loop from analysis through publish. · `backend/src/agents/__init__.py`
- [Agents](https://github.com/talelboussetta/hackfarm/blob/main/backend/src/agents/analyst.py): specialized roles · Analyst, architect, frontend, backend, business, integrator, validator, and GitHub agents. · `backend/src/agents/analyst.py`
- [LLM Layer](https://github.com/talelboussetta/hackfarm/blob/main/backend/src/llm/router.py): model router · Model/provider routing and prompt definitions for agents. · `backend/src/llm/router.py`
- [Runtime Core](https://github.com/talelboussetta/hackfarm/blob/main/backend/src/core/queue_manager.py): job services · Queueing, events, encryption, key management, and zip building. · `backend/src/core/queue_manager.py`
- [Integrations](https://github.com/talelboussetta/hackfarm/blob/main/backend/src/integrations/github.py): external adapters · Backend adapters for Appwrite, GitHub, and optional n8n automation. · `backend/src/integrations/github.py`
- [Artifacts](https://github.com/talelboussetta/hackfarm/blob/main/backend/src/core/zip_builder.py): generated output · Downloadable bundles and published codebases produced by the pipeline. · `backend/src/core/zip_builder.py`

### External services

Third-party systems the repo integrates with.

- **User**: client · Person using the web app to submit briefs and monitor generation.
- [Appwrite](https://github.com/talelboussetta/hackfarm/blob/main/backend/src/appwrite_client.py): external auth/data · Auth and user-scoped data backend used by the frontend and server. · `backend/src/appwrite_client.py`
- [GitHub](https://github.com/talelboussetta/hackfarm/blob/main/backend/src/integrations/github.py): publish target · Final destination for generated repositories. · `backend/src/integrations/github.py`
- [n8n](https://github.com/talelboussetta/hackfarm/blob/main/backend/src/integrations/n8n.py): automation bridge · Optional automation integration for workflow handoff. · `backend/src/integrations/n8n.py`

## Connections

- User → SPA: use · User interacts with the web app.
- SPA → Data Hooks: data · Pages use hooks for auth, submission, and streaming.
- SPA → Job UI: render · SPA presents job, history, settings, and stage views.
- Data Hooks → FastAPI API: call · Frontend talks only to backend API endpoints.
- Data Hooks → Appwrite: auth · Client config uses Appwrite for authentication/session state.
- FastAPI API → Auth: mount · API exposes authentication endpoints.
- FastAPI API → Jobs: mount · API exposes job lifecycle endpoints.
- FastAPI API → Stream: mount · API exposes live progress channels.
- FastAPI API → Admin & exports: mount · API exposes admin, settings, and download endpoints.
- Jobs → Ingestion: normalize · Incoming text and documents are converted into a brief.
- Jobs → Agent Pipeline: start · Jobs trigger the generation workflow.
- Ingestion → Agent Pipeline: input · Normalized brief becomes pipeline input.
- Agent Pipeline → Agents: coordinate · Pipeline dispatches specialized agent stages and refinement loops.
- Agents → LLM Layer: prompt · Agents obtain model responses through the LLM router and prompts.
- Agent Pipeline → Runtime Core: events · Pipeline uses queues, events, and packaging utilities.
- Runtime Core → Artifacts: build · Runtime packages generated code for download/export.
- Integrations → Appwrite: sync · Backend integrates with Appwrite for identity and user data.
- Integrations → GitHub: publish · Final project output can be published to GitHub.
- Integrations → n8n: optional · Optional automation bridge for external workflows.
- Agent Pipeline → Integrations: handoff · Publishing and external sync happen after validation/refinement.
- Stream → Runtime Core: broadcast · Streaming endpoints publish job events from the runtime.
- Admin & exports → Artifacts: download · Downloads route serves generated bundles.
