archsketch 0.1.0__tar.gz

archsketch-0.1.0/PKG-INFO

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: archsketch
+Version: 0.1.0
+Summary: A CLI tool that scans a project and infers system architecture
+Author: ArchSketch Team
+License: MIT
+Keywords: architecture,cli,diagram,mermaid
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: networkx>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Provides-Extra: graphviz
+Requires-Dist: graphviz>=0.20.0; extra == "graphviz"
+Provides-Extra: diff
+Requires-Dist: gitpython>=3.1.0; extra == "diff"
+
+# ArchSketch
+
+A Python CLI tool that scans any project directory and automatically infers its system architecture from common project files, then displays a beautiful ASCII diagram in your terminal.
+
+**No configuration needed.** Just point it at a folder.
+
+## Quick Start
+
+```bash
+# Clone the repo
+git clone https://github.com/yourusername/archsketch.git
+cd archsketch
+
+# Set up Python environment
+python -m venv venv
+
+# Activate (Windows)
+venv\Scripts\activate
+
+# Activate (macOS/Linux)
+source venv/bin/activate
+
+# Install
+pip install -e .
+
+# Run on any project!
+archsketch analyze /path/to/your/project
+```
+
+## Example Output
+
+```
+                          ARCHITECTURE SKETCH
+
+                    +--------------------------+
+                    |     >> Reverse Proxy     |
+                    |          Nginx           |
+                    +--------------------------+
+                                 |
+                                 v
+                    +--------------------------+
+                    |       ## Frontend        |
+                    |         Next.js          |
+                    +--------------------------+
+                                 |
+                                 v
+                    +--------------------------+
+                    |       @@ Backend         |
+                    |         FastAPI          |
+                    +--------------------------+
+                          |            |
+                          v            v
+              +----------------+ +----------------+
+              |   [] Database  | |    <> Cache   |
+              |   PostgreSQL   | |     Redis     |
+              +----------------+ +----------------+
+
++------------------------ Legend -------------------------+
+|  ## Frontend | @@ Backend | [] Database | <> Cache | >> Proxy |
++---------------------------------------------------------+
+```
+
+## Screenshots
+### Terminal output (analyze)
+<img width="1886" height="903" alt="image" src="https://github.com/user-attachments/assets/d3c7909b-f350-4a37-8786-cace590750ee" />
+
+### Exported SVG
+<img width="1917" height="1074" alt="image" src="https://github.com/user-attachments/assets/41fe360f-4b33-4e15-a96f-e86b3ce597bf" />
+
+## Usage
+
+### Analyze any project
+
+```bash
+archsketch analyze .                           # Current directory
+archsketch analyze /path/to/your/project       # Any project folder
+archsketch analyze ~/code/my-app               # Home directory path
+archsketch analyze . --compact                 # Diagram only, no detections table
+archsketch analyze . --no-table                # Same as --compact
+```
+
+### Export to Mermaid
+
+```bash
+archsketch export /path/to/project --format mermaid --output architecture.mmd
+```
+
+### Export to SVG (shareable image)
+
+```bash
+# Requires: pip install graphviz AND Graphviz binaries (https://graphviz.org/download/)
+archsketch export . --format graphviz --output architecture.svg
+
+# Or export DOT file (no binary needed), then convert: dot -Tsvg architecture.dot -o architecture.svg
+archsketch export . --format dot --output architecture.dot
+```
+
+Generates:
+
+```mermaid
+graph TD
+  frontend[Frontend: Next.js]
+  backend[Backend: FastAPI]
+  database[Database: PostgreSQL]
+  cache[Cache: Redis]
+
+  frontend --> backend
+  backend --> database
+  backend --> cache
+```
+
+### JSON output
+
+```bash
+archsketch analyze /path/to/project --json
+```
+
+### Show Mermaid in terminal
+
+```bash
+archsketch show /path/to/project
+```
+
+### Compare architecture between git refs (diff)
+
+Requires: `pip install gitpython`
+
+```bash
+archsketch diff main feature-branch
+archsketch diff HEAD~1 HEAD ./src
+```
+
+Shows added/removed components and edges (e.g. `+ Cache: Redis`, `- Database: MySQL`).
+
+### Explain in the diagram
+
+- **ASCII**: Each node box shows a short "From: ..." source line when available.
+- **Mermaid**: Comments in the `.mmd` file document which file each node came from.
+- **JSON**: Each node has `sources` and `explanation` for CI/scripting.
+
+### Stable JSON for CI
+
+Export includes `$schema`, `version`, and consistent shape. Schema: `schema/architecture.json`.
+
+```bash
+archsketch analyze . --output architecture.json
+```
+
+## What It Detects
+
+ArchSketch reads these files to understand your stack:
+
+| File | What it detects |
+|------|----------------|
+| `package.json` | React, Next.js, Vue, Express, NestJS, Prisma, Redis, Remix, Astro, Hono, Supabase |
+| `requirements.txt` | FastAPI, Flask, Django, Celery, psycopg2, redis, Supabase |
+| `pyproject.toml` | Same as requirements.txt |
+| `pom.xml` | Spring Boot, PostgreSQL, Redis, Kafka, Micronaut, Quarkus |
+| `build.gradle` / `build.gradle.kts` | Spring Boot, PostgreSQL, Redis (Gradle) |
+| `docker-compose.yml` | PostgreSQL, MySQL, Redis, Nginx, RabbitMQ, custom services |
+| `Dockerfile` | Base images (node, python, nginx) |
+| `.env` | Database URLs, Redis URLs, service connections |
+| `nginx.conf` | Nginx, upstream backends, SSL, WebSocket |
+| `Procfile` | web/worker process types, Gunicorn, Celery, Next.js |
+| `deployment.yaml`, `service.yaml`, `k8s/*.yaml` | Kubernetes Deployments, Services, Ingress, container images |
+| `*.tf` | Terraform (AWS RDS, Lambda, SQS, GCP, Azure resources) |
+
+## Detected Technologies
+
+| Role | Technologies |
+|------|-------------|
+| **Frontend** | React, Next.js, Vue.js, Nuxt.js, Angular, Svelte, **Remix**, **Astro**, **SolidJS**, **Qwik**, Preact |
+| **Backend** | Express, NestJS, FastAPI, Flask, Django, Fastify, **Hono**, **Elysia**, **Spring Boot** (pom.xml), Micronaut, Quarkus |
+| **Database** | PostgreSQL, MySQL, MongoDB, SQLite, **Supabase** |
+| **Cache** | Redis, Memcached |
+| **Reverse Proxy** | Nginx, Traefik, Caddy |
+| **Worker** | Celery, Bull, RQ |
+| **Queue** | RabbitMQ, Kafka |
+
+## How It Works
+
+```
+Your Project          ArchSketch Pipeline              Output
+    │                        │                           │
+    ├─ package.json    ──►   │                           │
+    ├─ requirements.txt ──►  │  1. Scan files            │
+    ├─ docker-compose.yml ►  │  2. Detect technologies   │  ──► ASCII Diagram
+    ├─ Dockerfile      ──►   │  3. Infer relationships   │  ──► Mermaid Export
+    └─ .env            ──►   │  4. Build graph           │  ──► JSON Data
+                             │  5. Render                 │
+```
+
+1. **Scanner** - Walks your project, finds architecture-related files
+2. **Detectors** - Parse each file type, extract technology signals
+3. **Inference Engine** - Apply rules to determine roles and connections
+4. **Renderer** - Output as ASCII art or Mermaid diagram
+
+## Try It On Popular Projects
+
+```bash
+# Clone any open source project and analyze it
+git clone https://github.com/tiangolo/full-stack-fastapi-template
+archsketch analyze full-stack-fastapi-template
+
+# Or your own projects
+archsketch analyze ~/code/my-saas-app
+```
+
+## Development
+
+### Run tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+### Project structure
+
+```
+archsketch/
+├── archsketch/
+│   ├── main.py              # CLI commands
+│   ├── scanner.py           # File discovery
+│   ├── models.py            # Data structures
+│   ├── detectors/           # Technology detection
+│   │   ├── package_json.py
+│   │   ├── requirements_txt.py
+│   │   ├── docker_compose.py
+│   │   └── dockerfile.py
+│   ├── inference/
+│   │   └── engine.py        # Architecture inference rules
+│   └── renderers/
+│       ├── ascii_renderer.py
+│       └── mermaid_renderer.py
+├── schema/
+│   └── architecture.json   # JSON schema for export (CI/scripting)
+├── tests/                  # 60+ tests
+├── samples/                 # Example projects
+└── pyproject.toml
+```
+
+## Requirements
+
+- Python 3.9+
+- No external services needed
+- Works offline
+
+## License
+
+MIT

archsketch-0.1.0/README.md

@@ -0,0 +1,251 @@
+# ArchSketch
+
+A Python CLI tool that scans any project directory and automatically infers its system architecture from common project files, then displays a beautiful ASCII diagram in your terminal.
+
+**No configuration needed.** Just point it at a folder.
+
+## Quick Start
+
+```bash
+# Clone the repo
+git clone https://github.com/yourusername/archsketch.git
+cd archsketch
+
+# Set up Python environment
+python -m venv venv
+
+# Activate (Windows)
+venv\Scripts\activate
+
+# Activate (macOS/Linux)
+source venv/bin/activate
+
+# Install
+pip install -e .
+
+# Run on any project!
+archsketch analyze /path/to/your/project
+```
+
+## Example Output
+
+```
+                          ARCHITECTURE SKETCH
+
+                    +--------------------------+
+                    |     >> Reverse Proxy     |
+                    |          Nginx           |
+                    +--------------------------+
+                                 |
+                                 v
+                    +--------------------------+
+                    |       ## Frontend        |
+                    |         Next.js          |
+                    +--------------------------+
+                                 |
+                                 v
+                    +--------------------------+
+                    |       @@ Backend         |
+                    |         FastAPI          |
+                    +--------------------------+
+                          |            |
+                          v            v
+              +----------------+ +----------------+
+              |   [] Database  | |    <> Cache   |
+              |   PostgreSQL   | |     Redis     |
+              +----------------+ +----------------+
+
++------------------------ Legend -------------------------+
+|  ## Frontend | @@ Backend | [] Database | <> Cache | >> Proxy |
++---------------------------------------------------------+
+```
+
+## Screenshots
+### Terminal output (analyze)
+<img width="1886" height="903" alt="image" src="https://github.com/user-attachments/assets/d3c7909b-f350-4a37-8786-cace590750ee" />
+
+### Exported SVG
+<img width="1917" height="1074" alt="image" src="https://github.com/user-attachments/assets/41fe360f-4b33-4e15-a96f-e86b3ce597bf" />
+
+## Usage
+
+### Analyze any project
+
+```bash
+archsketch analyze .                           # Current directory
+archsketch analyze /path/to/your/project       # Any project folder
+archsketch analyze ~/code/my-app               # Home directory path
+archsketch analyze . --compact                 # Diagram only, no detections table
+archsketch analyze . --no-table                # Same as --compact
+```
+
+### Export to Mermaid
+
+```bash
+archsketch export /path/to/project --format mermaid --output architecture.mmd
+```
+
+### Export to SVG (shareable image)
+
+```bash
+# Requires: pip install graphviz AND Graphviz binaries (https://graphviz.org/download/)
+archsketch export . --format graphviz --output architecture.svg
+
+# Or export DOT file (no binary needed), then convert: dot -Tsvg architecture.dot -o architecture.svg
+archsketch export . --format dot --output architecture.dot
+```
+
+Generates:
+
+```mermaid
+graph TD
+  frontend[Frontend: Next.js]
+  backend[Backend: FastAPI]
+  database[Database: PostgreSQL]
+  cache[Cache: Redis]
+
+  frontend --> backend
+  backend --> database
+  backend --> cache
+```
+
+### JSON output
+
+```bash
+archsketch analyze /path/to/project --json
+```
+
+### Show Mermaid in terminal
+
+```bash
+archsketch show /path/to/project
+```
+
+### Compare architecture between git refs (diff)
+
+Requires: `pip install gitpython`
+
+```bash
+archsketch diff main feature-branch
+archsketch diff HEAD~1 HEAD ./src
+```
+
+Shows added/removed components and edges (e.g. `+ Cache: Redis`, `- Database: MySQL`).
+
+### Explain in the diagram
+
+- **ASCII**: Each node box shows a short "From: ..." source line when available.
+- **Mermaid**: Comments in the `.mmd` file document which file each node came from.
+- **JSON**: Each node has `sources` and `explanation` for CI/scripting.
+
+### Stable JSON for CI
+
+Export includes `$schema`, `version`, and consistent shape. Schema: `schema/architecture.json`.
+
+```bash
+archsketch analyze . --output architecture.json
+```
+
+## What It Detects
+
+ArchSketch reads these files to understand your stack:
+
+| File | What it detects |
+|------|----------------|
+| `package.json` | React, Next.js, Vue, Express, NestJS, Prisma, Redis, Remix, Astro, Hono, Supabase |
+| `requirements.txt` | FastAPI, Flask, Django, Celery, psycopg2, redis, Supabase |
+| `pyproject.toml` | Same as requirements.txt |
+| `pom.xml` | Spring Boot, PostgreSQL, Redis, Kafka, Micronaut, Quarkus |
+| `build.gradle` / `build.gradle.kts` | Spring Boot, PostgreSQL, Redis (Gradle) |
+| `docker-compose.yml` | PostgreSQL, MySQL, Redis, Nginx, RabbitMQ, custom services |
+| `Dockerfile` | Base images (node, python, nginx) |
+| `.env` | Database URLs, Redis URLs, service connections |
+| `nginx.conf` | Nginx, upstream backends, SSL, WebSocket |
+| `Procfile` | web/worker process types, Gunicorn, Celery, Next.js |
+| `deployment.yaml`, `service.yaml`, `k8s/*.yaml` | Kubernetes Deployments, Services, Ingress, container images |
+| `*.tf` | Terraform (AWS RDS, Lambda, SQS, GCP, Azure resources) |
+
+## Detected Technologies
+
+| Role | Technologies |
+|------|-------------|
+| **Frontend** | React, Next.js, Vue.js, Nuxt.js, Angular, Svelte, **Remix**, **Astro**, **SolidJS**, **Qwik**, Preact |
+| **Backend** | Express, NestJS, FastAPI, Flask, Django, Fastify, **Hono**, **Elysia**, **Spring Boot** (pom.xml), Micronaut, Quarkus |
+| **Database** | PostgreSQL, MySQL, MongoDB, SQLite, **Supabase** |
+| **Cache** | Redis, Memcached |
+| **Reverse Proxy** | Nginx, Traefik, Caddy |
+| **Worker** | Celery, Bull, RQ |
+| **Queue** | RabbitMQ, Kafka |
+
+## How It Works
+
+```
+Your Project          ArchSketch Pipeline              Output
+    │                        │                           │
+    ├─ package.json    ──►   │                           │
+    ├─ requirements.txt ──►  │  1. Scan files            │
+    ├─ docker-compose.yml ►  │  2. Detect technologies   │  ──► ASCII Diagram
+    ├─ Dockerfile      ──►   │  3. Infer relationships   │  ──► Mermaid Export
+    └─ .env            ──►   │  4. Build graph           │  ──► JSON Data
+                             │  5. Render                 │
+```
+
+1. **Scanner** - Walks your project, finds architecture-related files
+2. **Detectors** - Parse each file type, extract technology signals
+3. **Inference Engine** - Apply rules to determine roles and connections
+4. **Renderer** - Output as ASCII art or Mermaid diagram
+
+## Try It On Popular Projects
+
+```bash
+# Clone any open source project and analyze it
+git clone https://github.com/tiangolo/full-stack-fastapi-template
+archsketch analyze full-stack-fastapi-template
+
+# Or your own projects
+archsketch analyze ~/code/my-saas-app
+```
+
+## Development
+
+### Run tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+### Project structure
+
+```
+archsketch/
+├── archsketch/
+│   ├── main.py              # CLI commands
+│   ├── scanner.py           # File discovery
+│   ├── models.py            # Data structures
+│   ├── detectors/           # Technology detection
+│   │   ├── package_json.py
+│   │   ├── requirements_txt.py
+│   │   ├── docker_compose.py
+│   │   └── dockerfile.py
+│   ├── inference/
+│   │   └── engine.py        # Architecture inference rules
+│   └── renderers/
+│       ├── ascii_renderer.py
+│       └── mermaid_renderer.py
+├── schema/
+│   └── architecture.json   # JSON schema for export (CI/scripting)
+├── tests/                  # 60+ tests
+├── samples/                 # Example projects
+└── pyproject.toml
+```
+
+## Requirements
+
+- Python 3.9+
+- No external services needed
+- Works offline
+
+## License
+
+MIT

archsketch-0.1.0/archsketch/__init__.py

@@ -0,0 +1,3 @@
+"""ArchSketch - Infer system architecture from project files."""
+
+__version__ = "0.1.0"

archsketch-0.1.0/archsketch/detectors/__init__.py

@@ -0,0 +1,27 @@
+"""Technology detectors for various file types."""
+
+from .package_json import detect_from_package_json
+from .requirements_txt import detect_from_requirements
+from .docker_compose import detect_from_docker_compose
+from .dockerfile import detect_from_dockerfile
+from .env_files import detect_from_env_files
+from .nginx_conf import detect_from_nginx_conf
+from .pom_xml import detect_from_pom_xml
+from .gradle import detect_from_gradle
+from .procfile import detect_from_procfile
+from .kubernetes import detect_from_kubernetes
+from .terraform import detect_from_terraform
+
+__all__ = [
+    "detect_from_package_json",
+    "detect_from_requirements",
+    "detect_from_docker_compose",
+    "detect_from_dockerfile",
+    "detect_from_env_files",
+    "detect_from_nginx_conf",
+    "detect_from_pom_xml",
+    "detect_from_gradle",
+    "detect_from_procfile",
+    "detect_from_kubernetes",
+    "detect_from_terraform",
+]