
Weekend Showcase Challenge: DocuForge
DocuForge is a serverless, Bedrock-powered agent that turns any public GitHub repository into a complete documentation set. It explores the codebase like a new engineer, using a Strands tool-using agent to decide which files matter, then generates an About summary, README, setup guide, a live Mermaid architecture diagram, and a "Post It" launch kit. Built on an async AWS stack (API Gateway, three Lambdas, DynamoDB, S3, and CloudFront), so it handles real repos without timing out.
Vision and What It Does
Every developer knows the feeling. You inherit a repository, open it, and there's no README, or worse, a README that is not updated. Documentation is the first thing we skip when we're racing a deadline and the last thing anyone wants to write. So codebases quietly rot into mysteries that only their original authors understand, and even they forget within a month.
DocuForge is my answer to that problem: an agent that reads your code and writes the docs for you. You paste a public GitHub repository URL, and it explores the project the way a new engineer would, figuring out what the entry points are, which modules matter, and how the pieces fit together. From that understanding it produces a full documentation set:
- About this project – a plain-language explanation of what the repo is and does.
- README – a polished overview with features, tech stack, and usage.
- Setup Guide – step-by-step instructions inferred from the project's configs.
- Architecture Diagram – a Mermaid diagram rendered from the code's real component relationships.
- Post It – a launch kit (a short article plus LinkedIn and tweet-thread posts) so shipping your work is as easy as shipping your code.
The philosophy is simple. Documentation should be a byproduct of building, not a separate chore. DocuForge turns "I'll write the README later" into "the README is already written."
How the Application Works
DocuForge runs as an asynchronous, job-based pipeline so it can handle real repositories without ever hitting a request timeout:
- You submit a repo. The web UI (hosted on S3, served through CloudFront) sends the GitHub URL to
POST /generateon API Gateway.
- A job is created instantly. A lightweight Starter Lambda writes a
PENDINGjob to DynamoDB, asynchronously invokes the Worker, and immediately returns ajob_id, no waiting.
- The Worker does the heavy lifting. A separate Worker Lambda (invoked in the background) fetches and samples the repo, runs the Strands agent to build an understanding of the code, generates the docs, builds the diagram, and produces the Post It kit. It writes the finished result back to DynamoDB and flips the job to
DONE.
- The UI polls for results. The browser polls
GET /result/{job_id}, backed by a Result Lambda, every few seconds until the job status isDONE(orERROR), then renders everything in a tabbed view with the Mermaid diagram drawn live in the browser.
This split means the browser only ever talks to two fast endpoints, while the slow generation work runs in the background and can take as long as it needs.
How I Built It
- Tool-using agent, not one giant prompt: Built the core with the Strands Agents SDK on Amazon Bedrock. The agent gets tools (list files, read a file, detect entry points) and decides what to inspect, the way a human explores an unfamiliar repo.
- Two models for two jobs: A stronger reasoning model (Claude Sonnet 4.5) drives multi-step code exploration and understanding; a lighter, faster model (Amazon Nova Lite) handles the writing (About, README, setup guide, Post It). Quality where it matters, low cost everywhere else.
- Async, three-Lambda design: The biggest architectural decision was going asynchronous. A synchronous pipeline hit API Gateway's 29-second integration limit on real repos. I split the work into a fast Starter, a background Worker, and a fast Result Lambda, coordinated through a DynamoDB job store. The browser polls for the result, so long-running analysis never times out.
- Smart file sampling: Large repos can overwhelm Lambda and the model's context, so the agent doesn't read everything. It scores files by importance (entry points, configs, top-level source), skips vendored dirs like
node_modules, and caps how many files it reads.
- Parallelized generation: The independent writing steps (About, README, setup guide, Post It) run concurrently in the Worker to keep total time down.
- Reliable structured output (the hard part): Getting clean JSON for the diagram was the biggest challenge. Early outputs arrived wrapped in markdown fences or malformed. Solved it with robust parsing that strips stray fences and safely extracts the JSON, plus a diagram builder that constructs valid Mermaid syntax deterministically instead of trusting the model to write it.
- Grounded generation: Every section is derived from the files the agent actually read, which keeps the output honest.
Challenges I Hit and Fixed
- The 29-second wall: My first version ran the whole pipeline in one synchronous Lambda. It worked in the logs but the browser kept failing at ~33 seconds. The culprit was API Gateway's hard 29-second integration timeout, the Lambda finished, but the request had already been cut off. This pushed me to re-architect into the async Starter/Worker/Result design with a DynamoDB job store and a polling UI. What looked like a bug became the best structural decision in the project.
- A retired model: Mid-build, calls started failing with "this model version has reached the end of its life." An older Claude model had been deprecated on Bedrock. I moved the reasoning model to Claude Sonnet 4.5, updated the IAM permissions and model access, and it was back online, a good reminder that model IDs are living dependencies.
- The invisible diagram: Everything generated correctly and the Mermaid text was sitting in DynamoDB, but the Architecture tab rendered as a blank white panel. The diagram was failing to render silently. I switched the frontend to Mermaid's render API so failures surface as a visible message instead of nothing, and cleared stale render state before each draw.
AWS Services and Architecture
- Amazon S3: Hosts the static web UI (the
index.htmlfrontend).
- Amazon CloudFront: Serves the UI globally over HTTPS; the Mermaid diagram renders live in the browser.
- Amazon API Gateway (HTTP API): Exposes
POST /generate(start a job) andGET /result/{job_id}(poll for results).
- AWS Lambda (Python) × 3: A Starter (creates the job, invokes the worker), a Worker (runs the full pipeline in the background), and a Result (returns job status and output).
- Amazon DynamoDB: A job store that tracks each request's status (
PENDING → RUNNING → DONE/ERROR) and holds the final result.
- GitHub REST API: Fetches repository contents (public repos), no
gitbinary needed in Lambda.
- Amazon Bedrock: The reasoning and writing engine behind the agent and generators.
- Architecture flow:
CloudFront + S3 (UI) → API Gateway → Starter Lambda → (async) Worker Lambda → GitHub REST API + Amazon Bedrock → DynamoDB → Result Lambda → back to the UI.
- Designed to evolve: The agent is already Strands-based, so there's a clear path to refactor it onto Amazon Bedrock AgentCore for managed tool orchestration, memory, and guardrails.
What I Learned Across the Summer
- Agents beat mega-prompts: Designing agents that use tools produces better, more grounded results than stuffing everything into one prompt.
- Right-sizing models: Splitting work across a strong reasoning model and a fast writing model balances quality and cost.
- Design around platform limits: Hitting API Gateway's 29-second ceiling pushed me to an async, job-based architecture, a more robust pattern that scales to any repo size.
- Taming LLM output: Forcing structured, predictable JSON, and writing defensive parsing, is essential for reliability.
- The full serverless stack: Wiring Lambda, API Gateway, S3, CloudFront, and DynamoDB into a real working product end to end.
- CloudFront caching gotcha: Learned to invalidate the cache so users actually see the latest deploy, not a stale version.
- Build for a problem you feel: The best builds solve something you personally struggle with. Documentation was mine.
App Link
- Live App Showcase: DocuForge Website
Builder Highlight
I find the articles and posts by @vivekraja interesting and insightful.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article