manojuio/fossfirst

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).