Metadata-Version: 2.4
Name: system-design
Version: 0.1.0
Summary: system-design — Architecture Intelligence Engine: turn any repo into a 3D architecture graph
License: MIT
Project-URL: Homepage, https://github.com/manish-surya/system-design
Project-URL: Repository, https://github.com/manish-surya/system-design
Project-URL: Documentation, https://github.com/manish-surya/system-design#readme
Project-URL: Bug Tracker, https://github.com/manish-surya/system-design/issues
Keywords: architecture,system-design,knowledge-graph,code-analysis,AI,developer-tools
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13
Requires-Dist: pydantic>=2.0
Requires-Dist: networkx>=3.0
Requires-Dist: tree-sitter>=0.23
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# system-design — Architecture Intelligence Engine

**Turn any repository into a living 3D architecture graph**

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Status: Alpha](https://img.shields.io/badge/status-alpha-orange.svg)]()

---

## What is system-design?

system-design is an **Architecture Intelligence Engine**. Point it at any software repository and it produces:

- **Architecture Knowledge Graph** — services, APIs, databases, events, infrastructure as a connected graph
- **3D Interactive System Design** — a Three.js scene with 3D components on a dark surface, wired & wireless connections
- **AI Architecture Analysis** — Claude analyzes the codebase and enriches the graph with descriptions, capabilities, domains
- **Slash Commands for Claude Code** — `/system-design`, `/service-map`, `/data-flow`, `/domain-map`, `/impact-analysis`

> *"I just joined this project. How does this system work?"*
> That question — answered in seconds, not weeks.

---

## Quick Start

```bash
pip install system-design

# Static analysis (no API key needed)
system-design analyze /path/to/your/repo
system-design visualize .zea/architecture_graph.json

# AI-powered full pipeline
export ANTHROPIC_API_KEY=your_key_here
system-design ai-analyze /path/to/your/repo
open .zea/architecture.html
```

---

## The 3D System Design

system-design renders architecture as a proper system design scene — not a floating sphere graph:

| Element | What it represents |
|---------|-------------------|
| Dark surface + grid | Deployment environment |
| Cubes | Services and backends |
| Cylinders | Databases and caches |
| Torus rings | Message queues (Kafka, RabbitMQ, SQS) |
| Octahedra | Domain events |
| Wide flat boxes | Frontends and gateways |
| Spheres | External systems (Stripe, Salesforce) |
| Tube curves | Wired connections (HTTP calls, DB queries) |
| Dashed arcs + signal rings | Wireless connections (events, pub-sub) |

---

## Pipeline

```
Repository
    ↓
Repository Discovery     →  repository_inventory.json
    ↓
Architecture Inference   →  architecture_graph.json
    ↓
AI Analysis (Claude)     →  architecture.json + architecture.md
    ↓
3D System Design Render  →  architecture.html
```

---

## CLI Commands

```bash
system-design analyze <repo>              # Static scan → graph
system-design ai-analyze <repo>           # Full AI pipeline → 3D design
system-design visualize <graph.json>      # Render 3D HTML from existing graph
system-design version                     # Show version
```

---

## Output Files

| File | Description |
|------|-------------|
| `repository_inventory.json` | Languages, frameworks, package managers, infrastructure |
| `architecture_graph.json` | Full knowledge graph — nodes and edges with evidence |
| `architecture.json` | AI-enriched analysis — descriptions, capabilities, domains |
| `architecture.md` | Human-readable system design document |
| `service-map.json` | Service dependency map |
| `domain-map.json` | Business domain groupings |
| `architecture.html` | **3D interactive system design** — open in any browser |

---

## Slash Commands (Claude Code)

Copy `skills/claude-code/SKILL.md` → `.claude/skills/system-design/SKILL.md` in your project:

| Command | Description |
|---------|-------------|
| `/system-design` | Full 3D system design of the current repo |
| `/service-map` | Service dependencies |
| `/data-flow` | User → API → Service → Database trace |
| `/domain-map` | Business domain groupings |
| `/impact-analysis <component>` | What breaks if this changes? |
| `/architecture-review` | Coupling, anti-patterns, tech debt |

---

## What system-design Detects

**Languages:** Python · TypeScript · JavaScript · Java · Go · C# · Rust · Kotlin · PHP · Ruby

**Frameworks:** FastAPI · Django · Flask · Next.js · React · Angular · Vue · Express · NestJS · Spring · Gin · Echo

**Infrastructure:** Docker · Kubernetes · Terraform · Helm · GitHub Actions · GitLab CI

**Databases:** PostgreSQL · MySQL · MongoDB · Redis · DynamoDB · SQLite · Elasticsearch · Cassandra

**Messaging:** Kafka · RabbitMQ · AWS SQS/SNS · NATS · Google Pub/Sub · BullMQ

---

## Benchmark Results

| Repository | Nodes | Score |
|-----------|-------|-------|
| fastapi (Python) | 109 | **100%** |
| express (JavaScript) | 40 | **100%** |
| nest (TypeScript) | 122 | **100%** |

---

## Roadmap

| Milestone | Feature | Status |
|-----------|---------|--------|
| 0–3 | CLI, Discovery, Graph, Inference | ✅ Done |
| 3.5 | AI Analysis (Claude API) | ✅ Done |
| 4–5 | Domain + Infrastructure Intelligence | 🔄 In progress |
| 6 | 3D System Design Viewer | ✅ Done |
| 7–10 | Impact Analysis, Reviews, AI Copilot, Digital Twin | ⬜ Planned |

---

## Contributing

```bash
git clone https://github.com/manish-surya/system-design.git
cd system-design
pip install -e ".[dev]"
pytest
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.

---

## License

MIT — see [LICENSE](LICENSE).

Built by [manish-surya-r](https://github.com/manish-surya-r) · Zealous Engineering

> *"Today Claude understands files. Tomorrow Claude understands systems."*
