Automated retro-documentation for existing codebases

About

Retro-Doc analyzes existing codebases to automatically generate documentation and structural insights. Upload a zip archive of your source code, and Retro-Doc extracts Abstract Syntax Trees (AST), Control Flow Graphs (CFG), and Data Flow Graphs (DFG), then makes the results explorable through an interactive UI, a RAG-powered chatbot, and an autonomous deep-analysis agent.

Built by the Caisse des Dépôts Informatique (ICDC).

Table of Contents

• Features
• Architecture
• Tech Stack
• Repository Structure
• Getting Started
• Contributing
• Maintainers & Contributors
• License

Features

• Code analysis pipeline — Upload a zip of source code, choose a target language, and run a multi-step analysis that extracts AST, CFG, and DFG graphs per file
• Graph explorer — Browse generated graphs interactively with Cytoscape-based visualization
• RAG chatbot — Ask questions about the analyzed codebase in a conversational interface, powered by LangChain with Azure AI Search as the vector store
• Deep analysis — Submit free-form queries for autonomous multi-step code analysis using DeepAgents, with PDF export
• Pipeline tracking — Monitor analysis progress in real time (pending, running, completed, failed)
• Multi-user support — Microsoft Entra ID authentication, per-user repository lists, and shared repository access

Architecture

graph LR
    User([User]) --> Frontend

    subgraph Azure
        Frontend["Frontend<br/>Angular"]
        Backend["Backend API<br/>FastAPI"]
        Worker["Worker<br/>Durable Functions"]
        Blob[(Blob Storage)]
        DB[(Cosmos DB<br/>for MongoDB)]
        Search[(Azure AI Search)]
        Gotenberg["Gotenberg<br/>PDF rendering"]
    end

    Frontend -->|REST API| Backend
    Backend -->|triggers| Worker
    Backend -->|RAG| Search
    Backend -->|PDF| Gotenberg
    Backend --> DB
    Backend --> Blob
    Worker --> Blob
    Worker --> DB
    Worker --> Search

Loading

Component	Role
Backend	FastAPI server handling authentication, CRUD operations, chatbot conversations (SSE streaming), and deep analysis orchestration
Frontend	Angular SPA providing the UI for repository management, graph exploration, chatbot, and deep analysis
Worker	Azure Durable Functions app that runs the analysis pipeline: zip extraction, per-file AST/CFG/DFG generation, and summary creation

Tech Stack

Backend (backend/)

FastAPI • Beanie • LangChain • LangGraph • DeepAgents • Mistral AI • Azure AI Search • Gotenberg • Loguru

Frontend (frontend/)

Angular 21 • Cytoscape.js • Mermaid • highlight.js

Worker (worker/)

Azure Durable Functions • javalang • NetworkX • Beanie • LangChain • Mistral AI • Loguru

Repository Structure

retro-doc/
├── backend/        # FastAPI REST API server
├── frontend/       # Angular SPA
├── worker/         # Azure Durable Functions analysis pipeline
└── LICENSE

Each component has its own dependency management and can be developed independently. See the README.md file in each folder for detailed documentation.

Getting Started

Prerequisites

• Python 3.12
• uv 0.10.9
• Node.js 22 (for the frontend and Azure Functions Core Tools)
• Azure Functions Core Tools v4 (for the worker)
• Docker (for Gotenberg)

Infrastructure Services

The backend and the worker rely on several external services. Some can be run or emulated locally for development:

Service	Local alternative	Production
MongoDB	Docker	Azure Cosmos DB for MongoDB
Blob Storage	Azurite (included via npx)	Azure Blob Storage
AI Search	No local emulator — requires an Azure AI Search instance	Azure AI Search
LLM / Embeddings	Any LangChain-supported chat model provider	Mistral AI / Azure OpenAI
PDF rendering	Docker	Gotenberg sidecar container

Note

An LLM endpoint is required for the full analysis pipeline (graph extraction + documentation generation), the RAG chatbot, and deep analysis. An embedding model and Azure AI Search are required for the chatbot and deep analysis. None of these can be emulated locally.

Backend

cd backend
cp .env.example .env        # fill in your credentials
uv sync
docker compose up -d        # start Gotenberg (PDF export)
uv run uvicorn app.main:app --host localhost --port 8000

API docs are available at http://localhost:8000/docs when APP_DEBUG=True.

Stop the Docker services when you're done with docker compose down.

Frontend

cd frontend
npm install
npm start

The app is served at http://localhost:4200/.

Worker

cd worker
cp .env.example .env        # fill in your credentials
uv sync

Start the local storage emulator and the Functions runtime in two terminals:

# Terminal 1
npx azurite --skipApiVersionCheck --location .azurite-data

# Terminal 2
func start

Contributing

Contributions are welcome. This project uses conventional commits and prek hooks for code quality.

uv run prek install   # backend & worker

Maintainers & Contributors

• Pierre Houdyer (@Grandvizir)
• Edgar Lopez (@KhadgarLopez)
• Mickaël Mayeur (@Mikatux)
• Pierre-Alexandre Broux (@pabroux)

License

This project is licensed under the Apache License 2.0.