{"id":51525553,"url":"https://github.com/jacklvd/arch-sketch","last_synced_at":"2026-07-08T21:01:06.937Z","repository":{"id":355345068,"uuid":"1226027426","full_name":"jacklvd/arch-sketch","owner":"jacklvd","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-03T05:19:41.000Z","size":12212,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-03T07:09:31.225Z","etag":null,"topics":["ai","system-design"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jacklvd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-30T22:36:39.000Z","updated_at":"2026-05-03T05:19:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jacklvd/arch-sketch","commit_stats":null,"previous_names":["jacklvd/arch-sketch"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jacklvd/arch-sketch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacklvd%2Farch-sketch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacklvd%2Farch-sketch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacklvd%2Farch-sketch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacklvd%2Farch-sketch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jacklvd","download_url":"https://codeload.github.com/jacklvd/arch-sketch/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacklvd%2Farch-sketch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35278166,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-08T02:00:06.796Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","system-design"],"created_at":"2026-07-08T21:01:06.133Z","updated_at":"2026-07-08T21:01:06.931Z","avatar_url":"https://github.com/jacklvd.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ArchSketch\n\nAI-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.\n\n## How It Works\n\nFill 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.\n\n## Stack\n\n| Layer | Technology |\n| --- | --- |\n| Frontend | Vite + React 19 + TypeScript |\n| Styling | Tailwind CSS v4 |\n| Diagrams | React Flow (`@xyflow/react`) |\n| Auto-layout | dagre |\n| State | Zustand |\n| Backend | FastAPI (Python 3.14) |\n| Local AI | Ollama — `gemma4:e2b` |\n| Cloud AI | Google Gemini — `gemini-2.5-flash` |\n| Validation | Pydantic v2 |\n\n## Project Structure\n\n```text\narch-sketch/\n├── backend/\n│   ├── main.py                  # FastAPI entry point\n│   ├── api/routes/generate.py   # POST /api/generate\n│   ├── models/                  # Pydantic request \u0026 diagram models\n│   ├── services/                # OllamaClient, GeminiClient, ModelRouter, JSON repair\n│   └── prompts/                 # Prompt templates per diagram type\n├── client/\n│   ├── src/\n│   │   ├── api/                 # Axios API client\n│   │   ├── components/          # InputForm, DiagramCanvas, DiagramTabs\n│   │   ├── nodes/               # Custom React Flow nodes\n│   │   ├── edges/               # Custom React Flow edges\n│   │   ├── lib/                 # iconRegistry, diagramMapper, layoutEngine\n│   │   ├── store/               # Zustand store\n│   │   └── types/               # TypeScript types matching JSON contract\n│   └── public/                  # Static assets \u0026 icons\n├── docker-compose.yml\n└── README.md\n```\n\n## Running the App\n\n### Option A — Docker (recommended)\n\nRequires [Docker Desktop](https://www.docker.com/products/docker-desktop/).\n\n```bash\n# Clone and enter the project\ngit clone \u003crepo-url\u003e arch-sketch\ncd arch-sketch\n\n# (Optional) set your Gemini API key for the cloud fallback\nexport GEMINI_API_KEY=your_key_here\n\n# Build and start all three services (client, backend, ollama)\ndocker compose up --build\n\n# First run only: pull the AI model into the Ollama container\ndocker compose exec ollama ollama pull gemma4:e2b\n```\n\n| Service | URL |\n| --- | --- |\n| Frontend | \u003chttp://localhost:3000\u003e |\n| Backend API | \u003chttp://localhost:8000\u003e |\n| Ollama | \u003chttp://localhost:11434\u003e |\n\nTo stop: `docker compose down`. Model data is persisted in the `ollama_data` Docker volume.\n\n---\n\n### Option B — Local Development\n\n#### Prerequisites\n\n- Python 3.14+, [Poetry](https://python-poetry.org/)\n- Node.js 18+, Yarn\n- [Ollama](https://ollama.com/) installed and running\n\n#### 1. Ollama\n\n```bash\nollama pull gemma4:e2b\n# Ollama starts automatically on most installs; if not:\nollama serve\n```\n\n#### 2. Backend\n\n```bash\ncd backend\n\n# Install dependencies\npoetry install\n\n# Add your Gemini API key (used as fallback if Ollama is unavailable)\necho \"GEMINI_API_KEY=your_key_here\" \u003e .env\n\n# Start the server\nsource venv/bin/activate\nuvicorn main:app --reload --port 8000\n```\n\n#### 3. Frontend\n\n```bash\ncd client\nyarn install\nyarn dev\n```\n\nThe app will be at **\u003chttp://localhost:5173\u003e**.\n\n---\n\n## Diagram Types\n\n| Type | Description |\n| --- | --- |\n| **High-Level Architecture** | Services, components, load balancers, databases, and their connections |\n| **Database Schema** | Tables, columns, PKs/FKs, and relationships with cardinality |\n| **API Design** | Services with endpoints, HTTP methods, and inter-service calls |\n| **Low-Level Design** | Internal layers — controllers, services, repositories, domain classes, and design patterns |\n\n## Features\n\n- **Tab switching** — generate all four diagram types and switch between them without losing any\n- **Regenerate** — re-run the last generation for the active diagram with one click\n- **Export PNG** — download the current diagram as a high-resolution PNG\n- **Ollama status** — live indicator in the sidebar shows whether the local model is reachable\n\n## Model Routing\n\n1. **Gemini** (`gemini-2.5-flash`) — tried first; best accuracy and detail for complex system designs\n2. **JSON repair** — strips markdown fences, fixes trailing commas, validates schema\n3. **Ollama** (`gemma4:e2b`) — local fallback if Gemini is unavailable or API key not set\n\n## Demo\n![high-level-design](assets/high-level-design.png)\n![database-design](assets/database-design.png)\n![low-level-design](assets/low-level-design.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacklvd%2Farch-sketch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjacklvd%2Farch-sketch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacklvd%2Farch-sketch/lists"}