RepoFriend

Problem and users

Reading an unfamiliar codebase starts with questions a README often skips: how the code is laid out, where the entry points are, and how to run it. RepoFriend is for developers who want a first draft of that documentation, plus optional inline comments they can review like any other change.

What I did

I designed and built RepoFriend: the Next.js interface with GitHub sign in, the FastAPI job API, the Celery worker, and the two LangGraph workflows described below. I am the only contributor to the public repository.

How it works

Submitting a repository URL creates a job record in PostgreSQL. A Celery worker picks the job up through Redis, so the API responds straight away and the interface polls for status: pending, processing, then completed or failed.

The documentation workflow is a LangGraph graph with six steps.

1. CloneClones the repository, using the signed in user's GitHub token for private repositories.
2. ScanWalks the file tree, skipping directories such as node_modules, up to 1,000 files.
3. AnalyzeExtracts structure from up to 20 code files: Python with the ast module, JavaScript and TypeScript with regular expressions.
4. GenerateSends the tree, file statistics, code analysis, README, and key config files to Claude Sonnet 4, which writes Markdown documentation.
5. SaveWrites the Markdown locally and uploads it to Amazon S3 when S3 is configured.
6. CleanupDeletes the cloned repository.

workflow.add_node("clone", self._clone_step)
workflow.add_node("scan", self._scan_step)
workflow.add_node("analyze", self._analyze_step)
workflow.add_node("generate", self._generate_step)
workflow.add_node("save", self._save_step)
workflow.add_node("cleanup", self._cleanup_step)

workflow.add_edge("clone", "scan")
workflow.add_edge("scan", "analyze")
workflow.add_edge("analyze", "generate")
workflow.add_edge("generate", "save")
workflow.add_edge("save", "cleanup")

Excerpt from backend/app/agents/documentation_agent.py.

Inline comments use a second LangGraph workflow. It clones the repository and has Claude add comments to the code files, then branches on access. If the user has write access, it creates a branch, commits the commented files, pushes, and opens a pull request against the default branch. Without write access, it saves the commented code to S3 so the user can read it in the app.

Decision and tradeoff

Separate steps with shared state, instead of one large prompt. Each step reads and writes a shared state object. When a step fails, it records the error and marks the job as failed. The steps after it see the error and pass through, while cleanup still runs, so no cloned repository is left behind. The error message is saved on the job, so the interface can show where it stopped.

The tradeoff is a fixed order: steps do not retry or reroute on their own. The only branch is the write access check in the comment workflow.

Comments reach the repository through a pull request rather than a direct commit to the default branch, so a person reviews every change before it lands.

Evaluation and limitations

• There is no automated check that the generated documentation is accurate. It is a first draft for a person to review.
• Analysis covers at most 20 code files, and each config file is cut at 5,000 characters, so large repositories are summarized from a partial view.
• JavaScript and TypeScript structure comes from regular expressions rather than a parser, which can miss or misread definitions.
• Generated comments should be reviewed in the pull request like any other change.

I have not published throughput or concurrency figures, because I have not documented a load test.