How talelboussetta/hackfarm works
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: main.py FastAPI API · __init__.py Agent Pipeline · github.py Integrations · App.jsx SPA
Components 19
Frontend
React/Vite SPA and its presentation/data-access layers.
- SPA · Main React/Vite application shell and routed pages.
frontend/src/App.jsx - Job UI · Dashboard pages and generation-focused UI components.
frontend/src/pages/Job.jsx - Data Hooks · 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 · Backend application entry and API route assembly.
backend/src/api/main.py - Auth · Authentication and session endpoints.
backend/src/api/routes/auth.py - Jobs · Job creation, control, and status endpoints.
backend/src/api/routes/jobs.py - Stream · Live progress/event streaming endpoints.
backend/src/api/routes/stream.py - Admin & exports · Settings, admin, and download endpoints.
backend/src/api/routes/downloads.py - Ingestion · Parsers and normalizer that turn uploaded documents into a brief.
backend/src/ingestion/normalizer.py - Agent Pipeline · Central multi-agent generation loop from analysis through publish.
backend/src/agents/__init__.py - Agents · Analyst, architect, frontend, backend, business, integrator, validator, and GitHub agents.
backend/src/agents/analyst.py - LLM Layer · Model/provider routing and prompt definitions for agents.
backend/src/llm/router.py - Runtime Core · Queueing, events, encryption, key management, and zip building.
backend/src/core/queue_manager.py - Integrations · Backend adapters for Appwrite, GitHub, and optional n8n automation.
backend/src/integrations/github.py - Artifacts · 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 · Person using the web app to submit briefs and monitor generation.
- Appwrite · Auth and user-scoped data backend used by the frontend and server.
backend/src/appwrite_client.py - GitHub · Final destination for generated repositories.
backend/src/integrations/github.py - n8n · Optional automation integration for workflow handoff.
backend/src/integrations/n8n.py
Connections 22
- 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.