SRS to Technical Document Agent

AI-powered tool that converts Software Requirements Specification (SRS) documents into comprehensive technical documentation using a multi-agent LangGraph workflow with intelligent parallel processing.

Problem Statement

Converting SRS documents into detailed technical documentation is time-consuming and requires deep analysis. This tool automates the process using AI agents to parse requirements and generate structured technical documentation with architecture diagrams, API specifications, and database schemas.

Features

• Multi-format Support - Upload SRS documents in PDF, DOCX, TXT, or Markdown
• Parallel Multi-Agent System - LangGraph supervisor orchestrates 6 worker agents simultaneously using ThreadPoolExecutor
• Comprehensive Analysis - Extracts functional/non-functional requirements, user roles, and use cases
• Technical Documentation - Generates architecture diagrams, API specs, database schemas, UML diagrams, and feature flows with Mermaid.js
• Real-time Progress - Server-Sent Events (SSE) streaming shows detailed progress during document analysis
• Export Options - Download as Markdown or PDF with rendered diagrams via WeasyPrint
• Project Management - In-memory session-based project storage (no database required)
• User Authentication - File-based JWT authentication with Authlib (no PostgreSQL required)
• LangSmith Integration - Optional cost tracking and trace monitoring
• OpenTelemetry Support - Optional local tracing via AI Toolkit

Tech Stack

• Backend - FastAPI with SSE streaming, Python 3.10+
• Frontend - Streamlit with multi-page navigation and authentication
• AI Framework - LangGraph with LangChain, OpenAI (gpt-4o-mini default)
• Authentication - Authlib, python-jose (JWT), passlib (Argon2 password hashing)
• Storage - In-memory (session-only), file-based user store (users.json)
• PDF Generation - WeasyPrint
• Diagrams - Mermaid.js
• Observability - LangSmith (optional), OpenTelemetry (optional)

Prerequisites

• Python 3.10+
• OpenAI API key
• System dependencies for PDF generation (macOS):

  brew install pango gdk-pixbuf libffi

Quick Start

1. Install Dependencies

# Navigate to project directory
cd srs-techdoc-agent

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install all dependencies
pip install -r requirements.txt

2. Configure Environment

# Copy example environment file
cp .env.example .env

# Edit .env and add your OpenAI API key
nano .env  # or use your favorite editor

Required in .env:

OPENAI_API_KEY=sk-your-openai-key-here
SECRET_KEY=your-secret-jwt-key-change-in-production

Optional configurations:

OPENAI_MODEL=gpt-4o-mini
OPENAI_TEMPERATURE=0.3
ACCESS_TOKEN_EXPIRE_MINUTES=30

# LangSmith (optional - for cost tracking)
# LANGSMITH_API_KEY=your_langsmith_key_here
# LANGSMITH_PROJECT=srs-techdoc-agent

# OpenTelemetry (optional - for local tracing)
# ENABLE_OTEL_TRACING=true
# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

3. Run the Application

Terminal 1 - Backend:

source .venv/bin/activate
uvicorn backend.main:app --reload --port 8000

Terminal 2 - Frontend:

source .venv/bin/activate
streamlit run frontend/app.py

4. Access the Application

• Frontend: http://localhost:8501
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

5. First Time Login

On first run, the application creates a default user:

• Username: admin
• Password: admin123

Change the password after first login for security.

Architecture Overview

LangGraph Supervisor Workflow

The application uses a supervisor-based parallel processing architecture:

graph TD
    START([START])
    PARALLEL[PARALLEL WORKERS NODE<br/>ThreadPoolExecutor - 6 Workers]
    REQ[Requirements<br/>Parser]
    ARCH[Architecture<br/>Designer]
    API[API<br/>Spec]
    DB[Database<br/>Designer]
    UML[UML Diagram<br/>Generator]
    FLOW[Features Flow<br/>Analyzer]
    COMPILER[COMPILER NODE<br/>Combines All Outputs]
    END_NODE([END])
    
    START --> PARALLEL
    PARALLEL --> REQ
    PARALLEL --> ARCH
    PARALLEL --> API
    PARALLEL --> DB
    PARALLEL --> UML
    PARALLEL --> FLOW
    REQ --> COMPILER
    ARCH --> COMPILER
    API --> COMPILER
    DB --> COMPILER
    UML --> COMPILER
    FLOW --> COMPILER
    COMPILER --> END_NODE
    
    style PARALLEL fill:#e1f5ff
    style COMPILER fill:#f0f0f0
    style START fill:#90EE90
    style END_NODE fill:#FFB6C1

Loading

Workflow Steps

1. Parallel Workers Node - Executes 6 specialized workers simultaneously using ThreadPoolExecutor:

   • Requirements Parser - Extracts functional/non-functional requirements, user roles, use cases
   • Architecture Designer - Creates system architecture, tech stack recommendations, deployment diagrams
   • API Specification - Designs RESTful API endpoints, authentication flows, request/response schemas
   • Database Designer - Generates database schemas, ERD diagrams, table relationships
   • UML Diagram Generator - Creates class diagrams, sequence diagrams, component diagrams
   • Features Flow Analyzer - Documents feature workflows, user journeys, data flows

2. Compiler Node - Aggregates all worker outputs into a single comprehensive technical documentation

Each worker receives the full SRS content for comprehensive analysis. The supervisor pattern ensures optimal parallel execution with individual LLM clients per worker to avoid rate limiting bottlenecks.

Key Features

• True Parallel Execution - ThreadPoolExecutor with staggered starts (200ms) prevents simultaneous rate limits
• Session-Only Memory - No checkpointer needed; state persists only during active session
• Rate Limit Management - Increased timeouts (300s) and retries (3) handle large documents
• Progress Tracking - Real-time SSE streaming provides granular progress updates
• Error Handling - Graceful fallbacks and detailed error messages

Project Structure

srs-techdoc-agent/
├── backend/
│   ├── main.py                          # FastAPI app with SSE endpoints
│   ├── api/
│   │   ├── auth_routes.py              # JWT authentication routes
│   │   └── client.py                   # API client utilities
│   ├── core/
│   │   ├── auth.py                     # JWT, password hashing
│   │   ├── langgraph_supervisor.py     # Supervisor workflow with 6 workers
│   │   ├── langgraph_pipeline.py       # Pipeline wrapper
│   │   ├── models.py                   # Pydantic models
│   │   ├── pdf_generator.py           # WeasyPrint PDF generation
│   │   └── srs_loader.py               # Multi-format document parsing
│   └── storage/
│       ├── project_store.py            # In-memory project storage
│       ├── database.py                 # SQLAlchemy models (unused)
│       └── users.json                  # File-based user store
├── frontend/
│   ├── app.py                          # Streamlit entry point with auth
│   ├── auth.py                         # Frontend auth utilities
│   ├── sse_client.py                   # SSE client for progress streaming
│   └── pages/
│       ├── home.py                     # Document upload and processing
│       └── projects.py                 # Project management
├── docs/                               # Comprehensive documentation
├── requirements.txt                    # Python dependencies
└── .env.example                        # Environment template

API Endpoints

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login and get JWT token
• GET /api/auth/me - Get current user info

Projects

• POST /api/upload - Upload SRS document
• GET /api/projects - List all projects (session-only)
• GET /api/project/{id} - Get project details
• DELETE /api/project/{id} - Delete project
• GET /api/stream-progress/{id} - SSE progress stream
• GET /api/download-markdown/{id} - Download as Markdown
• GET /api/download-pdf/{id} - Download as PDF

Storage & Authentication

In-Memory Storage

• Projects and files are stored in-memory during runtime
• Data is cleared when the server restarts
• No database setup required for quick development and testing

File-Based Authentication

• User credentials stored in backend/storage/users.json
• JWT tokens for session management
• Argon2 password hashing for security
• Default user: admin / admin123

Future Database Migration

For production deployments, consider migrating to PostgreSQL:

• SQLAlchemy models are already defined in backend/storage/database.py
• Documentation available in docs/POSTGRESQL_SETUP.md
• Enables persistent storage and multi-user isolation

Observability & Monitoring

LangSmith Integration (Optional)

Track costs, debug traces, and monitor performance:

1. Sign up at https://smith.langchain.com/
2. Get your API key
3. Add to .env:

   LANGSMITH_API_KEY=lsv2_pt_your_key_here
   LANGSMITH_PROJECT=srs-techdoc-agent

Features:

• Token usage and cost tracking per request
• Detailed trace visualization for each worker
• Performance metrics and latency analysis
• Evaluation datasets for testing

See docs/LANGSMITH_SETUP.md for full guide.

OpenTelemetry (Optional)

Local tracing with AI Toolkit trace viewer:

1. Enable in .env:

   ENABLE_OTEL_TRACING=true
   OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

2. Run AI Toolkit trace collector (port 4318)

3. View traces in VS Code AI Toolkit extension

Troubleshooting

Common Issues

Import Errors

# Ensure virtual environment is activated
source .venv/bin/activate

# Reinstall dependencies
pip install -r requirements.txt

PDF Generation Fails

# macOS: Install system dependencies
brew install pango gdk-pixbuf libffi

# Linux: 
sudo apt-get install libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0

Rate Limit Errors

• Reduce document size or split into smaller sections
• Check OpenAI API quota and billing
• Increase OPENAI_TIMEOUT in supervisor (default: 300s)

Authentication Issues

• Check SECRET_KEY is set in .env
• Verify users.json exists in backend/storage/
• Default credentials: admin / admin123

Port Already in Use

# Kill process on port 8000
lsof -ti:8000 | xargs kill -9

# Or use different port
uvicorn backend.main:app --reload --port 8001

Documentation

Comprehensive documentation available in /docs:

• ARCHITECTURE_OVERVIEW.md - System design and components
• LANGGRAPH_ARCHITECTURE.md - LangGraph workflow details
• LANGGRAPH_IMPLEMENTATION.md - Implementation guide
• AUTHENTICATION.md - Auth system overview
• LANGSMITH_SETUP.md - Observability setup
• SSE_STREAMING.md - Real-time progress implementation
• LARGE_DOCUMENT_HANDLING.md - Document chunking strategies
• FEATURES_FLOW_ALGORITHMS.md - Worker agent details

Contributing

This is a learning project. Feel free to:

• Explore the code and experiment
• Add new worker agents to the supervisor
• Improve prompts for better output quality
• Enhance the UI/UX
• Add database persistence
• Implement file upload limits and validation

License

Educational project - created to learn LangGraph, multi-agent systems, and AI application development.

---

Created to learn! 🚀