🏗️ System Design AI

An intelligent system design assistant that guides users through a structured, multi-step process to create comprehensive system designs. Built with FastAPI backend and modern HTML/CSS/JavaScript frontend.

✨ Features

• Multi-Step Process: Guided workflow from initial question → clarifying questions → complete design
• AI-Powered: Uses Google's Gemini AI for intelligent responses
• Interactive UI: Beautiful, responsive interface with progress tracking
• Streaming Responses: Real-time streaming of AI responses
• Mermaid Diagrams: Automatic rendering of system architecture diagrams
• Export Functionality: Download complete designs as text files
• Comprehensive Logging: Detailed logging for monitoring and debugging

🚀 Quick Start

Prerequisites

• Python 3.12+
• Google AI API Key (Get one here)
• uv package manager (recommended) or pip

Installation

1. Clone the repository

   git clone <repository-url>
   cd Design-Ai

2. Install dependencies

   uv sync

3. Set up environment variables

   export GOOGLE_API_KEY="your-google-ai-api-key-here"
   # or create a .env file with: GOOGLE_API_KEY=your-key-here

4. Run the application

   # Using Makefile (recommended)
   make run
   
   # Or directly with uv
   uv run python run.py

5. Open the frontend

   • Server: http://localhost:8000
   • Frontend: Open frontend/index.html in your browser

📁 Project Structure

Design-Ai/
├── backend/                 # FastAPI backend
│   ├── __init__.py
│   └── main.py             # Main FastAPI application
├── frontend/               # HTML/CSS/JS frontend
│   └── index.html          # Main frontend file
├── logs/                   # Application logs
│   └── system_design_ai.log
├── docs/                   # Documentation
├── static/                 # Static assets (future use)
├── run.py                  # Startup script
├── Makefile               # Development commands
├── pyproject.toml          # Project dependencies (uv)
├── config.template         # Environment config template
├── uv.lock                 # Dependency lock file
├── .gitignore             # Git ignore rules
└── README.md              # This file

🎯 How It Works

Step 1: Initial Question

• User describes their system design challenge
• Examples: "Design a chat app like WhatsApp", "Build a URL shortener"

Step 2: Clarifying Questions

• AI asks 5-7 targeted questions to understand requirements
• Covers scale, functionality, performance, data, constraints
• User provides detailed answers

Step 3: Complete Design

• AI generates comprehensive system design based on all gathered information
• Includes: Overview, Architecture, Components, Technology Stack, Scalability, Trade-offs
• Features Mermaid diagrams for visual architecture representation

🛠️ API Endpoints

• POST /clarify - Generate clarifying questions
• POST /design - Generate final system design
• Both endpoints support streaming responses

🎨 Frontend Features

• Progress Bar: Visual indication of current step
• Responsive Design: Works on desktop and mobile
• Streaming UI: Real-time display of AI responses
• Section-Based Layout: Organized display of design components
• Export Function: Download designs as text files
• Mermaid Integration: Automatic diagram rendering

🔧 Configuration

Environment Variables

• GOOGLE_API_KEY: Your Google AI API key (required)

Logging

• Logs are written to logs/system_design_ai.log
• Console output for development
• Configurable log levels

🧪 Development

Using Makefile (Recommended)

# Show all available commands
make help

# Complete setup (install dependencies + check config)
make setup

# Start development server with auto-reload
make dev

# Start production server
make run

# Check server status
make status

# View logs
make logs

# Stop server
make kill

Manual Development Mode

# Start backend with auto-reload using uv
uv run uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

# Or use the startup script with uv
uv run python run.py

Project Dependencies

• FastAPI: Modern web framework for APIs
• Uvicorn: ASGI server
• Google Generative AI: AI model integration
• Pydantic: Data validation

📝 Usage Examples

Example System Design Questions

• "Design a URL shortener like bit.ly that can handle 100M URLs"
• "Create a chat application like WhatsApp for 1 billion users"
• "Build a video streaming platform like YouTube"
• "Design a ride-sharing system like Uber"

Sample Clarifying Questions

1. How many users do you expect to use this system?
2. What are the core features you want to implement?
3. What are your performance requirements (latency, throughput)?
4. What data do you need to store and how much?
5. Are there any integration requirements with external systems?
6. What are your constraints (budget, timeline, existing tech stack)?
7. What are your non-functional requirements (security, compliance)?

🚨 Troubleshooting

Common Issues

1. Google AI API Key not set

   • Error: "API key not configured"
   • Solution: Set the GOOGLE_API_KEY environment variable

2. Model not found errors

   • Error: "models/gemini-2.5-flash is not found"
   • Solution: Check your API key and model availability

3. CORS errors

   • Error: "CORS Missing Allow Origin"
   • Solution: Ensure the backend is running and CORS is configured

Logs

Check logs/system_design_ai.log for detailed error information and request tracking.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📄 License

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

🙏 Acknowledgments

• Google AI for the Gemini model
• FastAPI for the excellent web framework
• Mermaid.js for diagram rendering
• The open-source community for inspiration and tools