# manojuio/fossfirst architecture

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

- Interactive diagram: https://gitdiagram.com/manojuio/fossfirst
- Repository: https://github.com/manojuio/fossfirst

## Overview

1. **What this repo is**
   - FOSSFirst is a **Python 3.11+**, local-first assistant for finding beginner-friendly GitHub issues and preparing a contribution path.
   - The architecture is centered on a **shared workflow engine** used by both a **CLI** and a **FastAPI backend**. There is **no database**; runtime coordination is handled in memory.

2. **Core orchestration boundary**
   - The heart of the system is the **graph-based pipeline** in `graph.py`, with shared execution state in `state.py`.
   - This is a **stateful, multi-step workflow** with an interrupt for human selection and a retry loop for patch generation/testing.
   - The README indicates it uses **LangGraph**-style checkpointed execution so a paused run can resume on the same thread/session.

3. **Agent layer**
   - `agents/` contains the LLM-driven task specialists:
     - `issue_ranker.py` scores issues for difficulty.
     - `codebase_mapper.py` identifies likely files to edit.
     - `patch_writer.py` drafts a unified diff.
     - `maintainer_simulator.py` acts as a reviewer and emits a verdict.
   - These are discrete prompt/decision stages rather than one monolithic model call, which makes the pipeline easy to diagram as separate nodes.

4. **External tool layer**
   - `tools/github_api.py` is the boundary to **GitHub’s public APIs** for searching issues, reading repo trees, and fetching raw file/README/CONTRIBUTING content.
   - `tools/ollama_client.py` connects to a **local Ollama instance** running the Qwen2.5-Coder model, so LLM inference stays on the user’s machine.
   - `tools/sandbox.py` is the validation boundary for generated patches; it checks diff format and runs syntax validation for Python files.

5. **End-to-end data flow**
   - The pipeline starts by searching GitHub for `good first issue` tickets in configured languages.
   - Issues are ranked by the local LLM, then the user chooses one.
   - The system fetches a **top-level file tree** for the target repo, maps likely edit targets, downloads the most relevant file content, and generates a patch.
   - The patch is tested in the sandbox; if it fails, the workflow loops back to rewrite the patch up to the configured retry limit.
   - Finally, repo guidance is pulled from `CONTRIBUTING.md`, the maintainer simulator reviews the result, and `final_report.py` produces the final verdict.

6. **CLI entry point**
   - `main.py` and `ui/cli.py` provide the terminal workflow.
   - The CLI is the most direct path through the graph: fetch → rank → human pick → patch/test loop → review → report.
   - This path is useful to diagram as a single interactive execution lane with a manual decision gate in the middle.

7. **Backend/API entry point**
   - `backend/main.py` exposes the same capabilities through FastAPI.
   - `backend/routes/issues.py` and `backend/routes/jobs.py` expose issue preparation and job lifecycle endpoints, while `backend/routes/webhooks.py` is a separate integration boundary.
   - `backend/services/agent_orchestrator.py` bridges HTTP requests to the shared workflow, so the backend does not duplicate agent logic.

8. **Async job handling**
   - `backend/utils/job_store.py` provides an **in-memory job store** for background execution and polling.
   - This is important for the architecture because the web API is not directly synchronous end-to-end; it starts jobs and lets clients poll status and results.
   - The job store is a runtime coordination mechanism, not durable persistence.

9. **UI layer**
   - `ui/interface.html` is a browser-facing static client that talks to the backend API.
   - It is not a separate server-rendered app; it’s a lightweight front end for issue ranking and contribution prep.
   - The browser UI and CLI both consume the same underlying agents, tools, and workflow.

10. **Key architectural constraints**
   - The system intentionally avoids cloning repositories, writing to GitHub, or creating PRs automatically.
   - It works from **GitHub search, raw content fetches, and local LLM inference**, with sandboxed validation as the only automated check.
   - The main boundaries to show in a diagram are: **GitHub API**, **local Ollama model**, **sandbox validation**, **in-memory workflow/job state**, and the two presentation surfaces (**CLI** and **FastAPI/browser**).

Main entry points: [`graph.py`](https://github.com/manojuio/fossfirst/blob/main/graph.py) (Workflow graph), [`tools/ollama_client.py`](https://github.com/manojuio/fossfirst/blob/main/tools/ollama_client.py) (Ollama client), [`backend/main.py`](https://github.com/manojuio/fossfirst/blob/main/backend/main.py) (API app), [`ui/cli.py`](https://github.com/manojuio/fossfirst/blob/main/ui/cli.py) (CLI UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_main(("CLI entry<br/>entrypoint<br/>[main.py]"))
  node_ui_cli["CLI UI<br/>terminal UI<br/>[cli.py]"]
  node_ui_html["Browser UI<br/>static client<br/>[interface.html]"]
end

subgraph group_backend["Backend"]
  node_backend_main(("API app<br/>[main.py]"))
  node_route_issues["Issues API<br/>route module<br/>[issues.py]"]
  node_route_jobs["Jobs API<br/>route module<br/>[jobs.py]"]
  node_route_webhooks["Webhooks<br/>integration route<br/>[webhooks.py]"]
  node_agent_orchestrator["Orchestrator<br/>service bridge"]
  node_job_store[("Job store<br/>in-memory state<br/>[job_store.py]")]
end

subgraph group_workflow["Workflow"]
  node_graph_py{{"Workflow graph<br/>pipeline<br/>[graph.py]"}}
  node_state_py["Run state<br/>execution state<br/>[state.py]"]
  node_final_report["Final report<br/>summary stage<br/>[final_report.py]"]
end

subgraph group_agents["Agents"]
  node_issue_ranker["Ranker<br/>LLM stage<br/>[issue_ranker.py]"]
  node_codebase_mapper["Mapper<br/>LLM stage<br/>[codebase_mapper.py]"]
  node_patch_writer["Patch writer<br/>LLM stage<br/>[patch_writer.py]"]
  node_maintainer_simulator["Reviewer<br/>LLM stage"]
end

subgraph group_tools["Tools"]
  node_github_api[("GitHub API<br/>external API<br/>[github_api.py]")]
  node_ollama_client[("Ollama client<br/>local model<br/>[ollama_client.py]")]
  node_sandbox["Sandbox<br/>validation<br/>[sandbox.py]"]
end

node_main -->|"invokes"| node_ui_cli
node_ui_cli -->|"runs"| node_graph_py
node_backend_main -->|"mounts"| node_route_issues
node_backend_main -->|"mounts"| node_route_jobs
node_backend_main -->|"mounts"| node_route_webhooks
node_route_issues -->|"dispatches"| node_agent_orchestrator
node_route_jobs -->|"tracks"| node_job_store
node_ui_html -->|"calls"| node_backend_main
node_agent_orchestrator -->|"starts"| node_graph_py
node_graph_py -->|"reads/writes"| node_state_py
node_graph_py -->|"fetches"| node_github_api
node_graph_py -->|"queries"| node_ollama_client
node_graph_py -->|"validates"| node_sandbox
node_graph_py -->|"step"| node_issue_ranker
node_graph_py -->|"step"| node_codebase_mapper
node_graph_py -->|"step"| node_patch_writer
node_graph_py -->|"step"| node_maintainer_simulator
node_graph_py -->|"finishes"| node_final_report
node_graph_py -->|"pause/resume"| node_job_store
node_issue_ranker -->|"uses"| node_ollama_client
node_codebase_mapper -->|"uses"| node_ollama_client
node_patch_writer -->|"uses"| node_ollama_client
node_maintainer_simulator -->|"uses"| node_ollama_client
node_graph_py -.->|"interrupt/retry"| node_state_py

click node_main "https://github.com/manojuio/fossfirst/blob/main/main.py"
click node_ui_cli "https://github.com/manojuio/fossfirst/blob/main/ui/cli.py"
click node_ui_html "https://github.com/manojuio/fossfirst/blob/main/ui/interface.html"
click node_backend_main "https://github.com/manojuio/fossfirst/blob/main/backend/main.py"
click node_route_issues "https://github.com/manojuio/fossfirst/blob/main/backend/routes/issues.py"
click node_route_jobs "https://github.com/manojuio/fossfirst/blob/main/backend/routes/jobs.py"
click node_route_webhooks "https://github.com/manojuio/fossfirst/blob/main/backend/routes/webhooks.py"
click node_agent_orchestrator "https://github.com/manojuio/fossfirst/blob/main/backend/services/agent_orchestrator.py"
click node_job_store "https://github.com/manojuio/fossfirst/blob/main/backend/utils/job_store.py"
click node_graph_py "https://github.com/manojuio/fossfirst/blob/main/graph.py"
click node_state_py "https://github.com/manojuio/fossfirst/blob/main/state.py"
click node_final_report "https://github.com/manojuio/fossfirst/blob/main/final_report.py"
click node_issue_ranker "https://github.com/manojuio/fossfirst/blob/main/agents/issue_ranker.py"
click node_codebase_mapper "https://github.com/manojuio/fossfirst/blob/main/agents/codebase_mapper.py"
click node_patch_writer "https://github.com/manojuio/fossfirst/blob/main/agents/patch_writer.py"
click node_maintainer_simulator "https://github.com/manojuio/fossfirst/blob/main/agents/maintainer_simulator.py"
click node_github_api "https://github.com/manojuio/fossfirst/blob/main/tools/github_api.py"
click node_ollama_client "https://github.com/manojuio/fossfirst/blob/main/tools/ollama_client.py"
click node_sandbox "https://github.com/manojuio/fossfirst/blob/main/tools/sandbox.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_main,node_ui_cli,node_ui_html toneBlue
class node_backend_main,node_route_issues,node_route_jobs,node_route_webhooks,node_agent_orchestrator,node_job_store toneAmber
class node_graph_py,node_state_py,node_final_report toneMint
class node_issue_ranker,node_codebase_mapper,node_patch_writer,node_maintainer_simulator toneRose
class node_github_api,node_ollama_client,node_sandbox toneIndigo
```

## Components

### Presentation

Interactive entry points for CLI and browser use

- [CLI entry](https://github.com/manojuio/fossfirst/blob/main/main.py): entrypoint · Starts the terminal workflow · `main.py`
- [CLI UI](https://github.com/manojuio/fossfirst/blob/main/ui/cli.py): terminal UI · Command-line interaction layer · `ui/cli.py`
- [Browser UI](https://github.com/manojuio/fossfirst/blob/main/ui/interface.html): static client · Browser-facing interface for the backend · `ui/interface.html`

### Backend

FastAPI surface plus job coordination

- [API app](https://github.com/manojuio/fossfirst/blob/main/backend/main.py): FastAPI app · HTTP server entrypoint · `backend/main.py`
- [Issues API](https://github.com/manojuio/fossfirst/blob/main/backend/routes/issues.py): route module · Issue search and preparation endpoints · `backend/routes/issues.py`
- [Jobs API](https://github.com/manojuio/fossfirst/blob/main/backend/routes/jobs.py): route module · Job lifecycle and polling endpoints · `backend/routes/jobs.py`
- [Webhooks](https://github.com/manojuio/fossfirst/blob/main/backend/routes/webhooks.py): integration route · External callback boundary · `backend/routes/webhooks.py`
- [Orchestrator](https://github.com/manojuio/fossfirst/blob/main/backend/services/agent_orchestrator.py): service bridge · Adapts HTTP requests to the shared workflow · `backend/services/agent_orchestrator.py`
- [Job store](https://github.com/manojuio/fossfirst/blob/main/backend/utils/job_store.py): in-memory state · Runtime job tracking and polling state · `backend/utils/job_store.py`

### Workflow

Shared orchestration and run state

- [Workflow graph](https://github.com/manojuio/fossfirst/blob/main/graph.py): pipeline · Shared stateful execution graph · `graph.py`
- [Run state](https://github.com/manojuio/fossfirst/blob/main/state.py): execution state · Shared workflow state object · `state.py`
- [Final report](https://github.com/manojuio/fossfirst/blob/main/final_report.py): summary stage · Produces the end-of-run verdict · `final_report.py`

### Agents

LLM-driven task specialists

- [Ranker](https://github.com/manojuio/fossfirst/blob/main/agents/issue_ranker.py): LLM stage · Scores issues by difficulty · `agents/issue_ranker.py`
- [Mapper](https://github.com/manojuio/fossfirst/blob/main/agents/codebase_mapper.py): LLM stage · Finds likely files to edit · `agents/codebase_mapper.py`
- [Patch writer](https://github.com/manojuio/fossfirst/blob/main/agents/patch_writer.py): LLM stage · Drafts candidate diffs · `agents/patch_writer.py`
- [Reviewer](https://github.com/manojuio/fossfirst/blob/main/agents/maintainer_simulator.py): LLM stage · Simulates maintainer feedback · `agents/maintainer_simulator.py`

### Tools

External API, model, and validation boundaries

- [GitHub API](https://github.com/manojuio/fossfirst/blob/main/tools/github_api.py): external API · Searches issues and fetches repo content · `tools/github_api.py`
- [Ollama client](https://github.com/manojuio/fossfirst/blob/main/tools/ollama_client.py): local model · Local Qwen2.5-Coder inference boundary · `tools/ollama_client.py`
- [Sandbox](https://github.com/manojuio/fossfirst/blob/main/tools/sandbox.py): validation · Checks patch format and Python syntax · `tools/sandbox.py`

## Connections

- CLI entry → CLI UI: invokes · Terminal entry passes control to the CLI
- CLI UI → Workflow graph: runs · CLI drives the shared workflow graph
- API app → Issues API: mounts · API exposes issue preparation routes
- API app → Jobs API: mounts · API exposes job lifecycle routes
- API app → Webhooks: mounts · API exposes webhook integration routes
- Issues API → Orchestrator: dispatches · Issue endpoints hand off to the orchestrator
- Jobs API → Job store: tracks · Jobs are stored in memory for polling
- Browser UI → API app: calls · Browser client talks to the API
- Orchestrator → Workflow graph: starts · Backend requests reuse the shared workflow
- Workflow graph → Run state: reads/writes · Workflow coordinates through shared state
- Workflow graph → GitHub API: fetches · Searches issues and pulls repository content
- Workflow graph → Ollama client: queries · Uses local LLM inference for decisions and drafts
- Workflow graph → Sandbox: validates · Checks generated patches and Python syntax
- Workflow graph → Ranker: step · Ranks candidate issues
- Workflow graph → Mapper: step · Identifies likely edit targets
- Workflow graph → Patch writer: step · Generates patch drafts
- Workflow graph → Reviewer: step · Reviews the proposed contribution
- Workflow graph → Final report: finishes · Produces the final verdict and summary
- Workflow graph → Job store: pause/resume · Backend runs can be tracked and resumed in memory
- Ranker → Ollama client: uses · Ranking is LLM-driven
- Mapper → Ollama client: uses · Mapping is LLM-driven
- Patch writer → Ollama client: uses · Patch drafting is LLM-driven
- Reviewer → Ollama client: uses · Review simulation is LLM-driven
- Workflow graph → Run state: interrupt/retry · Human selection and patch retry loop share the same run state