Tech Spec Agent

Technical Specification Agent for ANYON Platform - Automated TRD Generation

Overview

The Tech Spec Agent is an AI-powered system that automatically generates Technical Requirements Documents (TRDs), API specifications, database schemas, and architecture diagrams from Product Requirements Documents (PRDs) and design outputs.

Key Features

• Automated TRD Generation: Generate comprehensive technical specifications from PRDs with Section 3: System Architecture
• Technology Research: AI-powered research and recommendations for open-source libraries
• Interactive Decision-Making: Real-time WebSocket communication for user technology selections
• Code Analysis: Parse Google AI Studio code to infer API specifications
• Document Generation:
  • TRD with System Architecture section (textual description)
  • API specifications (OpenAPI/Swagger YAML)
  • Database schemas (SQL DDL + Mermaid ERD)
  • Architecture diagrams (Mermaid system flowcharts)
  • Technology stack documentation
• Quality Validation: 90% quality threshold with specialized architecture review agent
• Design Agent Integration: Seamless integration via shared PostgreSQL tables
• Production-Ready: Monitoring, error recovery, and high availability

---

Table of Contents

• Architecture
• Architecture Documentation
• Prerequisites
• Installation
• Configuration
• Running the Application
• Development
• Testing
• Deployment
• API Documentation
• Monitoring
• Troubleshooting
• Contributing

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     ANYON Platform                          │
│  (Frontend: TechSpecChat Component + Kanban Board)         │
└────────┬─────────────────────────────┬────────────────────┘
         │ REST API                    │ WebSocket
         ▼                             ▼
┌────────────────────────────────────────────────────────────┐
│              Tech Spec Agent (FastAPI)                      │
│  ┌──────────────────────────────────────────────────┐     │
│  │         LangGraph Workflow (21 Nodes)            │     │
│  └──────────────────────────────────────────────────┘     │
└────────┬──────────────────────────┬───────────────────────┘
         │                          │
         ▼                          ▼
┌─────────────────────┐    ┌─────────────────────┐
│  PostgreSQL DB      │    │  Redis Cache        │
│  • shared.* tables  │    │  • Tech research    │
│  • tech_spec.*      │    │  • Parsed code      │
│  • agent_error_logs │    │                     │
└─────────────────────┘    └─────────────────────┘

Technology Stack

• Framework: FastAPI 0.121+
• Workflow Engine: LangGraph 1.0.3+
• LLM: Claude Sonnet 4 (via Anthropic API)
• Database: PostgreSQL 15+
• Cache: Redis 5.2+
• Monitoring: Prometheus + Grafana
• Deployment: Docker + docker-compose

---

Architecture Documentation

Tech Spec Agent automatically generates THREE types of architecture documentation:

1. System Architecture Text (TRD Section 3)

• Generated at 70% workflow completion
• Textual description within the TRD document
• Includes architecture pattern, components, data flow, scalability

2. Database ERD (Mermaid)

• Generated at 85% workflow completion
• Mermaid Entity Relationship Diagram
• Shows tables, relationships, foreign keys
• Accompanies SQL DDL statements

3. System Architecture Diagram (Mermaid)

• Generated at 90% workflow completion
• Validated at 92% workflow completion
• Standalone Mermaid flowchart showing complete system topology:
  • Client Layer: Web and mobile applications
  • API Gateway: Load balancer with SSL/TLS
  • Application Layer: Multiple API server instances + business services
  • Data Layer: Primary database + read replicas + caching
  • External Services: OAuth, file storage, email, push notifications
  • Monitoring: Prometheus, Grafana, Sentry

Example Architecture Diagram Output:

flowchart TB
    subgraph Clients["Client Layer"]
        WebApp["Next.js Web App"]
        MobileApp["React Native App"]
    end
    subgraph Gateway["API Gateway"]
        LB["NGINX Load Balancer"]
    end
    subgraph Application["Application Layer"]
        API1["API Server 1"]
        API2["API Server 2"]
    end
    subgraph DataLayer["Data Layer"]
        DB["PostgreSQL Primary"]
        DBRep["PostgreSQL Replica"]
        Cache["Redis Cache"]
    end

    WebApp --> LB
    MobileApp --> LB
    LB --> API1
    LB --> API2
    API1 --> DB
    API2 --> DBRep
    DB -.-> DBRep
    API1 --> Cache

Loading

All architecture documents are validated through:

• Structure checks: Minimum 300 characters for TRD Section 3
• Database ERD validation: All tables and relationships present
• Architecture quality review (92% progress): Specialized AI agent scores 0-100 on:
  • Completeness (30 points): All layers present
  • Consistency (25 points): Matches selected technologies
  • Best Practices (25 points): Load balancing, caching, replication
  • Scalability (15 points): Horizontal scaling capability
  • Security (5 points): Authentication, encryption
• Pass threshold: >= 80/100 for architecture quality
• Overall TRD quality threshold: >= 90/100

See EXAMPLE_ARCHITECTURE_DIAGRAM.md for a complete example output.

---

Prerequisites

• Python: 3.11 or higher
• PostgreSQL: 15 or higher
• Redis: 5.2 or higher
• Docker: 20.10+ (optional, for containerized development)
• API Keys:
  • Anthropic API Key (Claude)
  • OpenAI API Key (Google AI Studio integration)
  • Tavily API Key (web search)

---

Installation

Option 1: Local Development (Without Docker)

1. Clone the repository:

   git clone https://github.com/anyon/tech-spec-agent.git
   cd tech-spec-agent

2. Create virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install --upgrade pip
   pip install -e .

4. Install development dependencies (for testing):

   pip install -e ".[dev]"

5. Install PostgreSQL and Redis:

   • PostgreSQL: Download from https://www.postgresql.org/download/
   • Redis: Download from https://redis.io/download/ or use Docker:

     docker run -d -p 6379:6379 redis:7-alpine

Option 2: Docker Development (Recommended)

1. Clone the repository:

   git clone https://github.com/anyon/tech-spec-agent.git
   cd tech-spec-agent

2. Start all services:

   docker-compose up -d

   This will start:

   • PostgreSQL (port 5432)
   • Redis (port 6379)
   • Tech Spec Agent API (port 8000)
   • Prometheus (port 9090)
   • Grafana (port 3001)

---

Configuration

Environment Variables

1. Copy the example environment file:

   cp .env.example .env

2. Edit .env and set your values:

   # Required - Database
   DATABASE_URL=postgresql+asyncpg://postgres:password@localhost:5432/anyon_db
   DATABASE_URL_SYNC=postgresql://postgres:password@localhost:5432/anyon_db
   
   # Required - LLM APIs
   ANTHROPIC_API_KEY=sk-ant-your-key-here
   OPENAI_API_KEY=sk-your-key-here
   TAVILY_API_KEY=tvly-your-key-here
   
   # Required - ANYON Integration
   ANYON_API_BASE_URL=https://anyon.platform/api
   ANYON_WEBHOOK_SECRET=your-webhook-secret
   ANYON_FRONTEND_URL=https://anyon.platform
   
   # Required - Security
   JWT_SECRET_KEY=your-super-secret-jwt-key-change-this-in-production
   
   # Optional - See .env.example for all options

Database Setup

1. Create database (if not using Docker):

   createdb anyon_db

2. Run migrations:

   alembic upgrade head

3. Verify database connection:

   python -c "from src.database.connection import db_manager; import asyncio; asyncio.run(db_manager.check_connection())"

---

Running the Application

Local Development

# Activate virtual environment
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Run the FastAPI server
uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

The API will be available at:

• API: http://localhost:8000
• API Docs: http://localhost:8000/docs
• Health Check: http://localhost:8000/health

Docker Development

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f tech-spec-agent

# Stop services
docker-compose down

Production

# Build production image
docker build -t tech-spec-agent:latest .

# Run production container
docker run -d \
  -p 8000:8000 \
  --env-file .env \
  tech-spec-agent:latest

---

Development

Project Structure

Tech Agent/
├── src/
│   ├── main.py                    # FastAPI application entry point
│   ├── config.py                  # Configuration management
│   ├── database/
│   │   ├── connection.py          # Database connection manager
│   │   └── models.py              # SQLAlchemy models
│   ├── api/
│   │   └── endpoints.py           # REST API endpoints
│   ├── langgraph/
│   │   ├── state.py               # State schema
│   │   ├── workflow.py            # Workflow definition
│   │   └── nodes/                 # Individual node implementations
│   ├── integration/
│   │   └── design_agent_loader.py # Design Agent integration
│   └── websocket/
│       └── connection_manager.py  # WebSocket manager
├── tests/
│   ├── conftest.py                # Pytest fixtures
│   ├── unit/                      # Unit tests
│   └── integration/               # Integration tests
├── alembic/                       # Database migrations
├── monitoring/                    # Prometheus & Grafana configs
├── .github/workflows/             # CI/CD pipelines
├── docker-compose.yml
├── Dockerfile
├── pyproject.toml
├── .env.example
└── README.md

Code Quality

We use several tools to maintain code quality:

# Format code with Black
black src/ tests/

# Sort imports with isort
isort src/ tests/

# Lint with Ruff
ruff check src/ tests/

# Type check with mypy
mypy src/

Pre-commit Hooks

Install pre-commit hooks to automatically run checks:

pip install pre-commit
pre-commit install

---

Testing

Run All Tests

# Run all tests with coverage
pytest --cov=src --cov-report=html --cov-report=term-missing -v

Run Specific Test Categories

# Unit tests only
pytest tests/unit/ -v

# Integration tests only
pytest tests/integration/ -v

# Run specific test file
pytest tests/unit/test_config.py -v

# Run with specific marker
pytest -m "slow" -v

Test Coverage

# Generate HTML coverage report
pytest --cov=src --cov-report=html

# Open coverage report
# Linux/Mac: open htmlcov/index.html
# Windows: start htmlcov/index.html

Coverage Target: 80%+

---

Deployment

Docker Deployment

1. Build image:

   docker build -t anyon/tech-spec-agent:1.0.0 .

2. Push to registry:

   docker push anyon/tech-spec-agent:1.0.0

3. Deploy to server:

   docker pull anyon/tech-spec-agent:1.0.0
   docker run -d \
     -p 8000:8000 \
     --env-file .env \
     --name tech-spec-agent \
     anyon/tech-spec-agent:1.0.0

Environment-Specific Configuration

• Development: ENVIRONMENT=development (enables debug, docs, reload)
• Staging: ENVIRONMENT=staging (limited debug, full logging)
• Production: ENVIRONMENT=production (no debug, no docs, optimized)

---

API Documentation

REST Endpoints

Method	Endpoint	Description
GET	/health	Health check endpoint
GET	/	API information
POST	/api/projects/{project_id}/start-tech-spec	Start Tech Spec session
GET	/api/tech-spec/sessions/{session_id}/status	Get session status
POST	/api/tech-spec/sessions/{session_id}/decisions	Submit user decision
GET	/api/tech-spec/sessions/{session_id}/trd	Download TRD

WebSocket Endpoint

• URL: wss://api.anyon.platform/ws/tech-spec/{session_id}?token={jwt_token}
• Protocol: Bidirectional JSON messages
• Use Case: Real-time progress updates and user interaction

Full API documentation: http://localhost:8000/docs (when running locally)

---

Monitoring

Prometheus Metrics

Access Prometheus at http://localhost:9090

Key Metrics:

• tech_spec_sessions_total - Total sessions created
• tech_spec_session_duration_seconds - Session duration histogram
• tech_spec_trd_quality_score - TRD quality score gauge
• tech_spec_errors_total - Total errors by type

Grafana Dashboards

Access Grafana at http://localhost:3001 (default login: admin/admin)

Pre-configured Dashboards:

1. Session Overview - Active, paused, completed sessions
2. Performance Metrics - Response times, throughput
3. Error Rates - Error trends by node
4. Technology Popularity - Most selected technologies

---

Troubleshooting

Database Connection Issues

# Check PostgreSQL is running
psql -U postgres -c "SELECT 1"

# Test connection from Python
python -c "from src.database.connection import db_manager; import asyncio; asyncio.run(db_manager.check_connection())"

Redis Connection Issues

# Check Redis is running
redis-cli ping

# Test from Python
python -c "import redis; r = redis.from_url('redis://localhost:6379/0'); print(r.ping())"

API Not Starting

# Check logs
docker-compose logs tech-spec-agent

# Check environment variables
env | grep DATABASE_URL

# Verify port is free
lsof -i :8000  # Linux/Mac
netstat -ano | findstr :8000  # Windows

Common Issues

1. "Database connection failed": Check DATABASE_URL is correct and PostgreSQL is running
2. "Redis connection failed": Check REDIS_URL and Redis service status
3. "Invalid API key": Verify ANTHROPIC_API_KEY and OPENAI_API_KEY are set correctly
4. "Health check failing": Check all services (PostgreSQL, Redis) are healthy

---

Contributing

We welcome contributions! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run tests: pytest
5. Check code quality: black src/ && ruff check src/ && mypy src/
6. Commit your changes: git commit -m "Add amazing feature"
7. Push to branch: git push origin feature/amazing-feature
8. Open a Pull Request

Code Standards

• Python Version: 3.11+
• Code Style: Black (line length 100)
• Type Hints: Required for all functions
• Test Coverage: Minimum 80%
• Documentation: Docstrings for all public functions

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Support

• Documentation: https://docs.anyon.platform/tech-spec-agent
• Issues: https://github.com/anyon/tech-spec-agent/issues
• Email: support@anyon.platform

---

Acknowledgments

• Design Agent - For providing the architectural patterns
• LangChain/LangGraph - For workflow orchestration
• Anthropic - For Claude Sonnet 4 LLM
• FastAPI - For the excellent web framework

---

Built with ❤️ by the ANYON Team