Skip to content

About

πŸ—οΈ AI-powered architecture analyzer that reverse-engineers your docs into living blueprints - upload PDFs, diagrams, or specs and get interactive architecture maps, AI-generated diagrams, quality scores, build plans, and a chat assistant that actually understands your system. Built with FastAPI + React + Claude.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Β 
Β 

Latest commit

Β 

History

47 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation


Anatomy AI

Anatomy AI

Dissect any project before writing a single line of code.


Python FastAPI React TypeScript Anthropic Tailwind


Feed it architecture docs, diagrams, specs, and whiteboard photos.
It reads everything, maps the system, generates interactive diagrams,
builds a development plan, and flags what's missing.


PDF Β· DOCX Β· Draw.io Β· PPTX Β· XLSX Β· Markdown Β· Images Β· TXT




πŸ’‘ The Problem

You inherit a project. There are 40 documents spread across Confluence, SharePoint, and email attachments. Some are architecture docs, some are diagrams, some are meeting notes with critical decisions buried in paragraph 17.

No one person knows the full picture. The architect left. The wiki is stale.

Anatomy reads all of it in minutes, understands the relationships, and hands you a complete system map β€” with gaps highlighted.


✨ Features at a Glance

πŸ“„ Ingest Anything

Drop any combination of document formats. PDFs, Word docs, PowerPoint decks, spreadsheets, draw.io diagrams, markdown, even whiteboard photos. Everything is parsed into a unified context.

🧠 AI Analysis

Map-Reduce pipeline extracts components, data flows, models, tech stack, NFRs, and gaps. Runs 3 batches in parallel with retry, resume, and real-time progress streaming.

πŸ—ΊοΈ Interactive Diagrams

10 diagram types β€” from C4 System Context to ER diagrams to deployment views. Glassmorphism-styled nodes, auto-layout with dagre, zoom, pan, minimap. Export to PNG or SVG.

πŸ’¬ Architecture Chat

Ask anything with full project context. "What are the security concerns?" "What happens if the queue goes down?" Responses stream in real-time.

πŸ“‹ Build Planning

Phased development plan with tasks, deliverables, acceptance criteria, risk assessment, tech recommendations, and team structure suggestions.

πŸ” Gap Detection

The killer feature. Finds what your docs don't say: "Auth mentioned but no auth strategy defined" "Database tech not specified for analytics store"


πŸš€ Quick Start

Prerequisites

Requirement Version
🐍 Python 3.12+
πŸ“¦ Node.js 18+
πŸ€– LLM API Key Anthropic or OpenAI

Install

# Clone
git clone <repo-url> && cd Anatomy

# Backend
cd backend
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env            # ← Edit with your LLM API credentials

# Frontend
cd ../frontend
npm install

Configure

Create backend/.env from the example:

# LLM Provider: "anthropic" or "openai"
ANATOMY_LLM_PROVIDER=anthropic
ANATOMY_LLM_API_KEY=your-api-key-here
# ANATOMY_LLM_BASE_URL=           # leave empty for default provider URL
ANATOMY_LLM_MODEL=claude-sonnet-4-20250514
ANATOMY_LLM_MODEL_DEEP=claude-sonnet-4-20250514

Tip

For deeper analysis, set LLM_MODEL_DEEP to a more powerful model like claude-opus-4-20250514 or gpt-4o.

Run

# Terminal 1 β€” API
cd backend && source venv/bin/activate
uvicorn app.main:app --reload --port 8000

# Terminal 2 β€” UI
cd frontend && npm run dev

β†’ Open http://localhost:5173


🎯 How to Use

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚   πŸ“ Select  │───▢│   πŸ“€ Upload  │───▢│   🧠 Analyze │───▢│  πŸ—ΊοΈ Explore  β”‚
β”‚   Project    β”‚    β”‚   Documents  β”‚    β”‚   (parallel) β”‚    β”‚  Diagrams    β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜
                                                                   β”‚
                                                            β”Œβ”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”
                                                            β”‚  πŸ’¬ Chat  /  β”‚
                                                            β”‚  πŸ“‹ Plan     β”‚
                                                            β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
Step What Happens
1. Pick a project Select existing or create new. Projects persist across browser sessions via localStorage.
2. Upload Drag & drop files. Any combination of 8 formats. All parsed instantly.
3. Analyze Click "Analyze Documents". Watch real-time SSE progress as batches extract in parallel.
4. Diagrams Switch tabs. Pick from 10 diagram types. Pan, zoom, drag nodes. Export PNG/SVG.
5. Chat Open the sliding panel. Ask anything β€” AI has full document + analysis context.
6. Plan Generate a phased build plan with tasks, risks, and blocking gaps.

πŸ“ Architecture

Project Structure (click to expand)
Anatomy/
β”œβ”€β”€ backend/                     Python 3.12+ / FastAPI
β”‚   β”œβ”€β”€ app/
β”‚   β”‚   β”œβ”€β”€ main.py              App entry, CORS, route registration
β”‚   β”‚   β”œβ”€β”€ config.py            Pydantic settings from .env
β”‚   β”‚   β”œβ”€β”€ api/                 Route handlers
β”‚   β”‚   β”‚   β”œβ”€β”€ upload.py        Project CRUD, file upload, delete
β”‚   β”‚   β”‚   β”œβ”€β”€ analyze.py       Map-reduce analysis (SSE), progress
β”‚   β”‚   β”‚   β”œβ”€β”€ diagrams.py      Diagram generation and retrieval
β”‚   β”‚   β”‚   β”œβ”€β”€ chat.py          Streaming chat (SSE)
β”‚   β”‚   β”‚   └── plan.py          Build plan generation
β”‚   β”‚   β”œβ”€β”€ services/            Business logic
β”‚   β”‚   β”‚   β”œβ”€β”€ parser.py        Multi-format doc parser (8 formats)
β”‚   β”‚   β”‚   β”œβ”€β”€ analyzer.py      Parallel map-reduce + synthesis
β”‚   β”‚   β”‚   β”œβ”€β”€ diagram_gen.py   AI diagram data generation
β”‚   β”‚   β”‚   β”œβ”€β”€ chat.py          Context-aware streaming chat
β”‚   β”‚   β”‚   └── planner.py       Build plan generation
β”‚   β”‚   β”œβ”€β”€ models/
β”‚   β”‚   β”‚   β”œβ”€β”€ schemas.py       Pydantic models (15 models)
β”‚   β”‚   β”‚   └── project.py       File-based JSON project store
β”‚   β”‚   └── utils/
β”‚   β”‚       β”œβ”€β”€ prompts.py       System prompt templates
β”‚   β”‚       └── file_utils.py    File I/O utilities
β”‚   β”œβ”€β”€ requirements.txt
β”‚   └── .env.example
β”‚
β”œβ”€β”€ frontend/                    React 19 / TypeScript / Vite
β”‚   └── src/
β”‚       β”œβ”€β”€ App.tsx              Layout, project restore, routing
β”‚       β”œβ”€β”€ store/useStore.ts    Zustand global state
β”‚       β”œβ”€β”€ hooks/useProject.ts  API hooks (SSE + REST)
β”‚       β”œβ”€β”€ components/
β”‚       β”‚   β”œβ”€β”€ project/         Project picker
β”‚       β”‚   β”œβ”€β”€ layout/          Header, Sidebar + progress bar
β”‚       β”‚   β”œβ”€β”€ upload/          Drag-and-drop zone
β”‚       β”‚   β”œβ”€β”€ analysis/        Results dashboard
β”‚       β”‚   β”œβ”€β”€ diagrams/        React Flow canvas + custom nodes
β”‚       β”‚   β”œβ”€β”€ chat/            Streaming chat panel
β”‚       β”‚   └── plan/            Build plan viewer
β”‚       β”œβ”€β”€ styles/theme.ts      Node color system
β”‚       └── types/index.ts       TypeScript interfaces
β”‚
β”œβ”€β”€ .gitignore
└── README.md

🧠 How the Analysis Engine Works

The core innovation is a parallel map-reduce pipeline that handles document sets of any size:

  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  β”‚            πŸ“„ 36 uploaded documents              β”‚
  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                       β”‚
                 _group_documents()
            (batches ≀ 120K chars each)
                       β”‚
  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  β”‚          15 batches  Β·  3 running in parallel    β”‚
  β”‚                                                  β”‚
  β”‚   β”Œβ”€β”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β”€β”               β”‚
  β”‚   β”‚ B1 βœ“ β”‚   β”‚ B2 βœ“ β”‚   β”‚ B3 ⏳ β”‚   ...        β”‚  MAP: extract_batch()
  β”‚   β””β”€β”€β”¬β”€β”€β”€β”˜   β””β”€β”€β”¬β”€β”€β”€β”˜   β””β”€β”€β”¬β”€β”€β”€β”˜               β”‚  (3Γ— retry + backoff)
  β”‚      β”‚          β”‚          β”‚                     β”‚
  β”‚      πŸ’Ύ         πŸ’Ύ         πŸ’Ύ                    β”‚  saved after EACH batch
  β”‚                                                  β”‚
  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                       β”‚
  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  β”‚         synthesize_extractions()                 β”‚  REDUCE: merge + dedup
  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                       β”‚
  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  β”‚          βœ… Unified AnalysisResult               β”‚
  β”‚    components Β· flows Β· models Β· gaps Β· NFRs     β”‚
  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Note

Resume support β€” if the browser disconnects or the server restarts mid-analysis, clicking "Analyze" again skips completed batches and picks up where it left off. Zero wasted API calls.

πŸ—ΊοΈ 10 Diagram Types

# Diagram Description
1 System Context (C4-L1) Bird's eye β€” system, actors, external systems
2 Container (C4-L2) Applications, data stores, protocols
3 Component (C4-L3) Internals of a single container
4 High-Level Design Layers, services, infrastructure boundaries
5 Low-Level Design Modules, classes, detailed interactions
6 Data Flow End-to-end data movement through the system
7 ER Diagram Entities, attributes, relationships
8 Sequence Service interaction flows over time
9 Deployment Infrastructure, cloud services, networking
10 Tech Stack Visual technology radar

πŸ› οΈ Tech Stack

Layer Technology Why
πŸ€– AI Anthropic Claude / OpenAI Large context windows, streaming support
⚑ Backend FastAPI + Python 3.12 Async, fast, great doc-parsing ecosystem
βš›οΈ Frontend React 19 + TypeScript Component model fits diagram rendering
πŸ—ΊοΈ Diagrams React Flow + dagre Interactive node graphs with auto-layout
🎨 Styling Tailwind CSS 4 Utility-first, rapid visual iteration
🎬 Animation Framer Motion Smooth transitions between views
πŸ“¦ State Zustand 5 Lightweight, zero boilerplate
πŸ“‘ Streaming Server-Sent Events Real-time progress, no WebSocket overhead
πŸ’Ύ Persistence File-based JSON Zero infrastructure β€” works fully offline
πŸ“„ Parsing PyMuPDF, python-docx, python-pptx, openpyxl, lxml Native parser per format

πŸ“‘ API Reference

Projects
Method Endpoint Description
POST /api/projects?name=X Create a new project
GET /api/projects List all projects
GET /api/projects/:id Get project + analysis + plan
DELETE /api/projects/:id Delete a project
POST /api/projects/:id/upload Upload files (multipart)
DELETE /api/projects/:id/documents/:docId Remove a document
Analysis
Method Endpoint Description
POST /api/analyze Run analysis (SSE stream) β€” {project_id}
POST /api/analyze?fresh=true Fresh analysis (wipe previous)
GET /api/projects/:id/analysis Get analysis results
GET /api/projects/:id/analysis-progress Poll extraction progress
Diagrams
Method Endpoint Description
POST /api/diagrams/generate Generate diagram β€” {project_id, diagram_type}
GET /api/projects/:id/diagrams/:type Get generated diagram
Chat & Planning
Method Endpoint Description
POST /api/chat Chat (SSE stream) β€” {project_id, message}
GET /api/projects/:id/chat-history Get conversation history
DELETE /api/projects/:id/chat-history Clear conversation
POST /api/plan/generate Generate build plan β€” {project_id}
GET /api/projects/:id/plan Get generated plan

βš™οΈ Configuration

All environment variables use the ANATOMY_ prefix in backend/.env:

Variable Required Default Description
LLM_PROVIDER anthropic LLM provider (anthropic or openai)
LLM_API_KEY βœ… - API key for your LLM provider
LLM_BASE_URL - Custom base URL (leave empty for default)
LLM_MODEL claude-sonnet-4-20250514 Model for extraction, diagrams, chat
LLM_MODEL_DEEP claude-sonnet-4-20250514 Model for synthesis and planning
MAX_FILE_SIZE_MB 50 Max upload size per file

πŸ’‘ Pro Tips

Tip

Upload everything together β€” Cross-references between a PRD, draw.io diagram, and API spec produce much richer analysis than uploading them separately.

Tip

Start with System Context β€” Generate the C4 Level 1 diagram first for the big picture, then drill into Container and Component.

Tip

Check gaps first β€” Gap detection is the fastest way to surface undocumented decisions and assumptions.

Tip

Resume, don't restart β€” If analysis disconnects, just click Analyze again. Completed batches are skipped instantly. Zero wasted API calls.


πŸ—οΈ Design Decisions

Decision Rationale
SQLite for storage Zero infrastructure. No database to provision. Works offline.
Map-reduce with parallel batching Handles 50+ docs without hitting context limits. 3x faster.
SSE over WebSockets Simpler protocol, works through proxies, no state to manage.
Zustand over Redux Same capability, fraction of the boilerplate.
React Flow over D3 First-class React. Built-in pan, zoom, minimap, export.
dagre for layout Deterministic hierarchical layout. Great for architecture diagrams.



Built with Anthropic Claude and a lot of architectural opinions.


If it can read your architecture, it can find what's missing.



About

πŸ—οΈ AI-powered architecture analyzer that reverse-engineers your docs into living blueprints - upload PDFs, diagrams, or specs and get interactive architecture maps, AI-generated diagrams, quality scores, build plans, and a chat assistant that actually understands your system. Built with FastAPI + React + Claude.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages