https://github.com/jacklvd/arch-sketch
https://github.com/jacklvd/arch-sketch
ai system-design
Last synced: about 16 hours ago
JSON representation
- Host: GitHub
- URL: https://github.com/jacklvd/arch-sketch
- Owner: jacklvd
- License: mit
- Created: 2026-04-30T22:36:39.000Z (2 months ago)
- Default Branch: master
- Last Pushed: 2026-05-03T05:19:41.000Z (2 months ago)
- Last Synced: 2026-05-03T07:09:31.225Z (2 months ago)
- Topics: ai, system-design
- Language: TypeScript
- Homepage:
- Size: 11.6 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ArchSketch
AI-powered system design diagram generator. Describe your system and get interactive, draggable architecture diagrams — high-level architecture, database schema, API design, and low-level component diagrams.
## How It Works
Fill in your system requirements (quest, functional/non-functional requirements, design description), pick a diagram type, and click **Generate Diagram**. The backend routes the request to a local Ollama model (`gemma4:e2b`) first, falling back to Gemini (`gemini-2.5-flash`) for complex cases or if Ollama is unavailable.
## Stack
| Layer | Technology |
| --- | --- |
| Frontend | Vite + React 19 + TypeScript |
| Styling | Tailwind CSS v4 |
| Diagrams | React Flow (`@xyflow/react`) |
| Auto-layout | dagre |
| State | Zustand |
| Backend | FastAPI (Python 3.14) |
| Local AI | Ollama — `gemma4:e2b` |
| Cloud AI | Google Gemini — `gemini-2.5-flash` |
| Validation | Pydantic v2 |
## Project Structure
```text
arch-sketch/
├── backend/
│ ├── main.py # FastAPI entry point
│ ├── api/routes/generate.py # POST /api/generate
│ ├── models/ # Pydantic request & diagram models
│ ├── services/ # OllamaClient, GeminiClient, ModelRouter, JSON repair
│ └── prompts/ # Prompt templates per diagram type
├── client/
│ ├── src/
│ │ ├── api/ # Axios API client
│ │ ├── components/ # InputForm, DiagramCanvas, DiagramTabs
│ │ ├── nodes/ # Custom React Flow nodes
│ │ ├── edges/ # Custom React Flow edges
│ │ ├── lib/ # iconRegistry, diagramMapper, layoutEngine
│ │ ├── store/ # Zustand store
│ │ └── types/ # TypeScript types matching JSON contract
│ └── public/ # Static assets & icons
├── docker-compose.yml
└── README.md
```
## Running the App
### Option A — Docker (recommended)
Requires [Docker Desktop](https://www.docker.com/products/docker-desktop/).
```bash
# Clone and enter the project
git clone arch-sketch
cd arch-sketch
# (Optional) set your Gemini API key for the cloud fallback
export GEMINI_API_KEY=your_key_here
# Build and start all three services (client, backend, ollama)
docker compose up --build
# First run only: pull the AI model into the Ollama container
docker compose exec ollama ollama pull gemma4:e2b
```
| Service | URL |
| --- | --- |
| Frontend | |
| Backend API | |
| Ollama | |
To stop: `docker compose down`. Model data is persisted in the `ollama_data` Docker volume.
---
### Option B — Local Development
#### Prerequisites
- Python 3.14+, [Poetry](https://python-poetry.org/)
- Node.js 18+, Yarn
- [Ollama](https://ollama.com/) installed and running
#### 1. Ollama
```bash
ollama pull gemma4:e2b
# Ollama starts automatically on most installs; if not:
ollama serve
```
#### 2. Backend
```bash
cd backend
# Install dependencies
poetry install
# Add your Gemini API key (used as fallback if Ollama is unavailable)
echo "GEMINI_API_KEY=your_key_here" > .env
# Start the server
source venv/bin/activate
uvicorn main:app --reload --port 8000
```
#### 3. Frontend
```bash
cd client
yarn install
yarn dev
```
The app will be at ****.
---
## Diagram Types
| Type | Description |
| --- | --- |
| **High-Level Architecture** | Services, components, load balancers, databases, and their connections |
| **Database Schema** | Tables, columns, PKs/FKs, and relationships with cardinality |
| **API Design** | Services with endpoints, HTTP methods, and inter-service calls |
| **Low-Level Design** | Internal layers — controllers, services, repositories, domain classes, and design patterns |
## Features
- **Tab switching** — generate all four diagram types and switch between them without losing any
- **Regenerate** — re-run the last generation for the active diagram with one click
- **Export PNG** — download the current diagram as a high-resolution PNG
- **Ollama status** — live indicator in the sidebar shows whether the local model is reachable
## Model Routing
1. **Gemini** (`gemini-2.5-flash`) — tried first; best accuracy and detail for complex system designs
2. **JSON repair** — strips markdown fences, fixes trailing commas, validates schema
3. **Ollama** (`gemma4:e2b`) — local fallback if Gemini is unavailable or API key not set
## Demo
