system-design 0.1.0__py3-none-any.whl

system_design/ai/analyzer.py

@@ -0,0 +1,276 @@
+"""
+system-design AI Architecture Analyzer
+=============================
+Uses Claude to analyze a repository inventory + static graph and produce
+a rich structured architecture description for 3D rendering.
+
+Requires: ANTHROPIC_API_KEY environment variable.
+Falls back gracefully to static inference if API key not set.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+
+from system_design.ai.prompts import SYSTEM_PROMPT, USER_PROMPT_TEMPLATE
+from system_design.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+_MAX_NODES_IN_PROMPT = 60  # truncate to keep token count manageable
+_MAX_EDGES_IN_PROMPT = 80
+
+
+def _summarize_nodes(nodes: list[dict]) -> str:
+    lines = []
+    for n in nodes[:_MAX_NODES_IN_PROMPT]:
+        lines.append(f"  - [{n.get('type','?')}] id={n.get('id','?')}  name={n.get('name','?')}")
+    if len(nodes) > _MAX_NODES_IN_PROMPT:
+        lines.append(f"  ... and {len(nodes) - _MAX_NODES_IN_PROMPT} more")
+    return "\n".join(lines)
+
+
+def _summarize_edges(edges: list[dict]) -> str:
+    lines = []
+    for e in edges[:_MAX_EDGES_IN_PROMPT]:
+        lines.append(
+            f"  - {e.get('source_id','?')} --[{e.get('type','?')}]--> {e.get('target_id','?')}"
+        )
+    if len(edges) > _MAX_EDGES_IN_PROMPT:
+        lines.append(f"  ... and {len(edges) - _MAX_EDGES_IN_PROMPT} more")
+    return "\n".join(lines)
+
+
+def _build_prompt(inventory: dict, graph: dict) -> str:
+    nodes = graph.get("nodes", [])
+    edges = graph.get("edges", [])
+    inv   = inventory
+
+    return USER_PROMPT_TEMPLATE.format(
+        repo_name       = inv.get("repository_name", "unknown"),
+        primary_language= inv.get("primary_language", "unknown"),
+        languages       = ", ".join(
+            f"{l['language']}({l['file_count']} files)"
+            for l in inv.get("languages", [])
+        ) or "none detected",
+        frameworks      = ", ".join(
+            f['framework'] for f in inv.get("frameworks", [])
+        ) or "none detected",
+        package_managers= ", ".join(
+            p['manager'] for p in inv.get("package_managers", [])
+        ) or "none",
+        infrastructure  = ", ".join(
+            i['type'] for i in inv.get("infrastructure", [])
+        ) or "none detected",
+        has_tests       = inv.get("has_tests", False),
+        has_ci          = inv.get("has_ci", False),
+        total_files     = inv.get("total_files", 0),
+        node_count      = len(nodes),
+        nodes_summary   = _summarize_nodes(nodes),
+        edge_count      = len(edges),
+        edges_summary   = _summarize_edges(edges),
+    )
+
+
+def _extract_json(text: str) -> dict:
+    """Extract JSON from Claude's response (handles markdown code blocks)."""
+    # Try direct parse first
+    try:
+        return json.loads(text.strip())
+    except json.JSONDecodeError:
+        pass
+
+    # Try extracting from ```json ... ``` block
+    m = re.search(r"```(?:json)?\s*(\{.*?\})\s*```", text, re.DOTALL)
+    if m:
+        try:
+            return json.loads(m.group(1))
+        except json.JSONDecodeError:
+            pass
+
+    # Find the first { ... } block
+    m = re.search(r"\{.*\}", text, re.DOTALL)
+    if m:
+        try:
+            return json.loads(m.group(0))
+        except json.JSONDecodeError:
+            pass
+
+    raise ValueError("Could not extract valid JSON from Claude response")
+
+
+def _static_fallback(inventory: dict, graph: dict) -> dict:
+    """Generate a minimal architecture analysis without Claude."""
+    nodes = graph.get("nodes", [])
+    edges = graph.get("edges", [])
+    repo  = inventory.get("repository_name", "system")
+
+    LAYER_MAP = {
+        "frontend": "frontend", "backend": "service", "monolith": "service",
+        "service": "service", "gateway": "gateway", "worker": "service",
+        "database": "data", "cache": "data",
+        "queue": "messaging", "topic": "messaging", "event": "messaging",
+        "rest_api": "gateway", "graphql_api": "gateway", "grpc_api": "gateway",
+        "webhook": "gateway", "cluster": "infrastructure", "namespace": "infrastructure",
+        "pod": "infrastructure", "external_system": "external",
+        "domain": "service", "repository": "service", "team": "external",
+    }
+    SHAPE_MAP = {
+        "frontend": "cuboid", "backend": "cube", "monolith": "cube",
+        "service": "cube", "gateway": "cuboid", "worker": "cuboid",
+        "database": "cylinder", "cache": "cylinder",
+        "queue": "torus", "topic": "torus", "event": "octahedron",
+        "rest_api": "panel", "graphql_api": "panel", "grpc_api": "panel",
+        "cluster": "cuboid", "external_system": "sphere", "domain": "cuboid",
+    }
+    WIRELESS_TYPES = {"PUBLISHES", "CONSUMES", "INVOKES"}
+
+    components = []
+    for n in nodes:
+        ntype = n.get("type", "unknown")
+        components.append({
+            "node_id":      n.get("id", ""),
+            "display_name": n.get("name", n.get("id", "")),
+            "description":  f"A {ntype} component in {repo}",
+            "capabilities": [],
+            "layer":        LAYER_MAP.get(ntype, "service"),
+            "shape":        SHAPE_MAP.get(ntype, "cube"),
+            "importance":   3,
+        })
+
+    connections = []
+    for e in edges:
+        etype = e.get("type", "CALLS")
+        connections.append({
+            "source_id": e.get("source_id", ""),
+            "target_id": e.get("target_id", ""),
+            "edge_type":  etype,
+            "wire_type":  "wireless" if etype in WIRELESS_TYPES else "wired",
+            "label":      etype.lower().replace("_", " "),
+        })
+
+    return {
+        "system_description": f"Software system: {repo}",
+        "system_type":        "unknown",
+        "components":         components,
+        "connections":        connections,
+        "domains":            [],
+    }
+
+
+def analyze_with_claude(
+    inventory: dict,
+    graph: dict,
+    model: str = "claude-opus-4-6",
+) -> dict:
+    """
+    Send repository inventory + graph to Claude and return structured
+    architecture analysis.
+
+    Returns a dict with keys: system_description, system_type,
+    components, connections, domains.
+
+    If ANTHROPIC_API_KEY is not set, falls back to static analysis.
+    """
+    api_key = os.environ.get("ANTHROPIC_API_KEY")
+    if not api_key:
+        logger.warning(
+            "ANTHROPIC_API_KEY not set — using static fallback analysis. "
+            "Set the key to enable AI-powered architecture analysis."
+        )
+        return _static_fallback(inventory, graph)
+
+    try:
+        import anthropic
+    except ImportError:
+        logger.warning("anthropic package not installed. Run: pip install anthropic")
+        return _static_fallback(inventory, graph)
+
+    logger.info(f"Sending repository to Claude ({model}) for architecture analysis...")
+
+    prompt = _build_prompt(inventory, graph)
+    client = anthropic.Anthropic(api_key=api_key)
+
+    try:
+        response = client.messages.create(
+            model=model,
+            max_tokens=4096,
+            system=SYSTEM_PROMPT,
+            messages=[{"role": "user", "content": prompt}],
+        )
+        raw = response.content[0].text
+        result = _extract_json(raw)
+        logger.info(
+            f"AI analysis complete: {len(result.get('components', []))} components, "
+            f"{len(result.get('connections', []))} connections, "
+            f"{len(result.get('domains', []))} domains"
+        )
+        return result
+    except Exception as e:
+        logger.warning(f"Claude API call failed ({e}) — using static fallback")
+        return _static_fallback(inventory, graph)
+
+
+def save_analysis(analysis: dict, output_dir: Path) -> dict[str, Path]:
+    """Save AI analysis as separate output files."""
+    output_dir.mkdir(parents=True, exist_ok=True)
+    outputs: dict[str, Path] = {}
+
+    # architecture.json (enriched graph)
+    arch_path = output_dir / "architecture.json"
+    arch_path.write_text(json.dumps(analysis, indent=2), encoding="utf-8")
+    outputs["architecture"] = arch_path
+
+    # service-map.json
+    services = [
+        c for c in analysis.get("components", [])
+        if c.get("layer") in {"service", "gateway", "frontend"}
+    ]
+    sm_path = output_dir / "service-map.json"
+    sm_path.write_text(json.dumps({
+        "services": services,
+        "connections": [
+            c for c in analysis.get("connections", [])
+            if c.get("edge_type") in {"CALLS", "DEPENDS_ON"}
+        ],
+    }, indent=2), encoding="utf-8")
+    outputs["service_map"] = sm_path
+
+    # domain-map.json
+    dm_path = output_dir / "domain-map.json"
+    dm_path.write_text(json.dumps({
+        "domains": analysis.get("domains", []),
+    }, indent=2), encoding="utf-8")
+    outputs["domain_map"] = dm_path
+
+    # architecture.md
+    md_lines = [
+        f"# {analysis.get('system_description', 'Architecture')}",
+        f"\n**System Type:** {analysis.get('system_type', 'unknown')}\n",
+        "\n## Components\n",
+    ]
+    for c in analysis.get("components", []):
+        md_lines.append(f"### {c['display_name']} `[{c.get('layer','?')}]`")
+        md_lines.append(f"{c.get('description', '')}")
+        caps = c.get("capabilities", [])
+        if caps:
+            md_lines.append("\n**Capabilities:**")
+            for cap in caps:
+                md_lines.append(f"- {cap}")
+        md_lines.append("")
+
+    if analysis.get("domains"):
+        md_lines.append("\n## Domains\n")
+        for d in analysis["domains"]:
+            md_lines.append(f"### {d['name']}")
+            md_lines.append(d.get("description", ""))
+            md_lines.append("")
+
+    md_path = output_dir / "architecture.md"
+    md_path.write_text("\n".join(md_lines), encoding="utf-8")
+    outputs["architecture_md"] = md_path
+
+    logger.info(f"Saved analysis artifacts to {output_dir}")
+    return outputs

system_design/ai/prompts.py

@@ -0,0 +1,83 @@
+"""Prompt templates for system-design AI architecture analysis."""
+
+SYSTEM_PROMPT = """You are a senior software architect with deep expertise in system design, microservices, distributed systems, and cloud-native architecture.
+
+Your job is to analyze a software repository and produce a precise, structured architectural description that will be used to render an interactive 3D system design diagram.
+
+Rules:
+- Be concrete and specific. Use actual service names from the codebase.
+- Infer capabilities from the code evidence provided.
+- Classify every component into a layer: frontend | gateway | service | data | messaging | infrastructure | external
+- Classify every connection as: wired (synchronous HTTP/gRPC/function call) OR wireless (async event/queue/pub-sub)
+- Return ONLY valid JSON. No markdown, no explanation outside the JSON."""
+
+USER_PROMPT_TEMPLATE = """Analyze this software repository and produce a structured system design description.
+
+=== REPOSITORY INVENTORY ===
+Name: {repo_name}
+Primary Language: {primary_language}
+Languages detected: {languages}
+Frameworks detected: {frameworks}
+Package managers: {package_managers}
+Infrastructure: {infrastructure}
+Has tests: {has_tests}
+Has CI: {has_ci}
+Total files: {total_files}
+
+=== ARCHITECTURE GRAPH (from static analysis) ===
+Nodes ({node_count}):
+{nodes_summary}
+
+Edges ({edge_count}):
+{edges_summary}
+
+=== TASK ===
+Return a JSON object with this exact schema:
+
+{{
+  "system_description": "One clear sentence describing what this system does",
+  "system_type": "monolith | microservices | monorepo | library | cli | data-pipeline | unknown",
+  "components": [
+    {{
+      "node_id": "<matches a node id from the graph above>",
+      "display_name": "<human-readable name>",
+      "description": "<what this component does, 1-2 sentences>",
+      "capabilities": ["<specific capability>", "<specific capability>"],
+      "layer": "frontend | gateway | service | data | messaging | infrastructure | external",
+      "shape": "cube | cuboid | cylinder | torus | octahedron | sphere | panel",
+      "importance": 1-5
+    }}
+  ],
+  "connections": [
+    {{
+      "source_id": "<node id>",
+      "target_id": "<node id>",
+      "edge_type": "CALLS | READS | WRITES | PUBLISHES | CONSUMES | DEPENDS_ON",
+      "wire_type": "wired | wireless",
+      "label": "<short label like 'REST API', 'event', 'SQL query'>"
+    }}
+  ],
+  "domains": [
+    {{
+      "name": "<domain name, e.g. Commerce, Identity, Billing>",
+      "description": "<what business area>",
+      "node_ids": ["<node ids that belong to this domain>"]
+    }}
+  ]
+}}
+
+For components, choose shapes based on their type:
+- service/backend/monolith → cube or cuboid
+- database/storage → cylinder
+- queue/message broker → torus
+- event → octahedron
+- frontend/UI → cuboid (wide, flat)
+- gateway/load balancer → cuboid (wide)
+- external system → sphere
+- infrastructure/cluster → cuboid (tall)
+
+For connections:
+- HTTP calls, database queries, function calls → wired
+- Events, pub/sub, queues, webhooks → wireless
+
+Include ALL nodes from the graph in components. Add connections that make architectural sense even if not explicitly in the edge list — infer from the codebase context."""

system_design/cli/commands/ai_analyze.py

@@ -0,0 +1,106 @@
+"""system-design ai-analyze — AI-powered architecture analysis using Claude."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+
+def ai_analyze_command(
+    repo_path: Path,
+    output_dir: Path,
+    model: str,
+    verbose: bool,
+) -> None:
+    """
+    Full pipeline:
+    1. Static scan  →  repository_inventory.json + architecture_graph.json
+    2. Claude AI    →  architecture.json + architecture.md + service-map.json + domain-map.json
+    3. 3D render    →  architecture.html
+    """
+    from system_design.core.config import ZEAConfig
+    from system_design.core.logging import setup_logging
+    from system_design.discovery.scanner import save_inventory, scan_repository
+    from system_design.graph.builder import AKGBuilder
+    from system_design.graph.serializer import save_graph
+    from system_design.inference.engine import InferenceEngine
+    from system_design.ai.analyzer import analyze_with_claude, save_analysis
+    from system_design.visualization.threejs_generator import generate_html
+
+    setup_logging(verbose)
+    if not repo_path.exists():
+        console.print(f"[red]Error:[/red] Path not found: {repo_path}")
+        raise typer.Exit(1)
+
+    config = ZEAConfig(output_dir=output_dir, verbose=verbose)
+    console.print(f"\n[bold blue]system-design[/bold blue] AI Analysis — [cyan]{repo_path.resolve().name}[/cyan]\n")
+
+    # ── Stage 1: Static discovery ──────────────────────────────────────────────
+    with console.status("[bold]Stage 1/4:[/bold] Scanning repository…"):
+        inventory = scan_repository(repo_path, config)
+        save_inventory(inventory, config.output_path("repository_inventory.json"))
+
+    console.print(
+        f"  [green]✓[/green] Discovery: [b]{len(inventory.languages)}[/b] languages, "
+        f"[b]{len(inventory.frameworks)}[/b] frameworks, "
+        f"[b]{inventory.total_files}[/b] files"
+    )
+
+    # ── Stage 2: Static graph ──────────────────────────────────────────────────
+    with console.status("[bold]Stage 2/4:[/bold] Building knowledge graph…"):
+        builder = AKGBuilder(inventory)
+        akg = builder.build()
+        engine = InferenceEngine(akg, repo_path)
+        akg = engine.run()
+        save_graph(akg, config.output_path("architecture_graph.json"))
+
+    console.print(
+        f"  [green]✓[/green] Graph: [b]{akg.node_count}[/b] nodes, [b]{akg.edge_count}[/b] edges"
+    )
+
+    # ── Stage 3: AI analysis ───────────────────────────────────────────────────
+    with console.status("[bold]Stage 3/4:[/bold] AI architecture analysis (Claude)…"):
+        inventory_dict = json.loads(
+            config.output_path("repository_inventory.json").read_text()
+        )
+        graph_dict = json.loads(
+            config.output_path("architecture_graph.json").read_text()
+        )
+        analysis = analyze_with_claude(inventory_dict, graph_dict, model=model)
+        analysis["_repo_name"] = inventory.repository_name
+        outputs = save_analysis(analysis, output_dir)
+
+    console.print(
+        f"  [green]✓[/green] AI analysis: [b]{len(analysis.get('components',[]))}[/b] components, "
+        f"[b]{len(analysis.get('connections',[]))}[/b] connections, "
+        f"[b]{len(analysis.get('domains',[]))}[/b] domains"
+    )
+
+    # ── Stage 4: 3D render ─────────────────────────────────────────────────────
+    with console.status("[bold]Stage 4/4:[/bold] Rendering 3D system design…"):
+        html_path = config.output_path("architecture.html")
+        generate_html(analysis, html_path)
+
+    console.print(f"  [green]✓[/green] 3D system design rendered\n")
+
+    # ── Summary ────────────────────────────────────────────────────────────────
+    console.print(f"[bold green]✓[/bold green] Complete. Artifacts in [cyan]{output_dir}[/cyan]:\n")
+    files = [
+        ("repository_inventory.json", "Static discovery"),
+        ("architecture_graph.json",   "Knowledge graph"),
+        ("architecture.json",         "AI architecture analysis"),
+        ("architecture.md",           "System design document"),
+        ("service-map.json",          "Service dependency map"),
+        ("domain-map.json",           "Domain map"),
+        ("architecture.html",         "3D interactive system design"),
+    ]
+    for fname, desc in files:
+        p = output_dir / fname
+        if p.exists():
+            console.print(f"  [dim]{fname:35}[/dim] {desc}")
+
+    console.print(f"\n  [bold]Open:[/bold] {output_dir / 'architecture.html'}\n")

system_design/cli/commands/analyze.py

@@ -0,0 +1,98 @@
+"""system-design analyze — full pipeline: Discovery → Graph → Inference."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+# Default output directory
+_DEFAULT_OUTPUT = Path(".system-design")
+
+from system_design.core.config import ZEAConfig
+from system_design.core.logging import setup_logging
+from system_design.discovery.scanner import save_inventory, scan_repository
+from system_design.graph.builder import AKGBuilder
+from system_design.graph.serializer import save_graph
+from system_design.inference.engine import InferenceEngine
+
+console = Console()
+
+
+def analyze_command(
+    repo_path: Path,
+    output_dir: Path = Path(".system-design"),
+    verbose: bool = False,
+    skip_inference: bool = False,
+) -> None:
+    """Analyze a repository and generate the Architecture Knowledge Graph."""
+    setup_logging(verbose)
+
+    if not repo_path.exists():
+        console.print(f"[red]Error:[/red] Path does not exist: {repo_path}")
+        raise typer.Exit(1)
+
+    config = ZEAConfig(output_dir=output_dir, verbose=verbose)
+
+    # --- Stage 1: Repository Discovery ---
+    console.print(f"\n[bold blue]system-design[/bold blue] Analyzing [cyan]{repo_path.resolve().name}[/cyan]\n")
+
+    with console.status("[bold green]Stage 1/3:[/bold green] Repository Discovery..."):
+        inventory = scan_repository(repo_path, config)
+        inv_path = config.output_path("repository_inventory.json")
+        save_inventory(inventory, inv_path)
+
+    _print_inventory_summary(inventory)
+
+    # --- Stage 2: Build AKG skeleton ---
+    with console.status("[bold green]Stage 2/3:[/bold green] Building Knowledge Graph..."):
+        builder = AKGBuilder(inventory)
+        akg = builder.build()
+
+    # --- Stage 3: Architecture Inference ---
+    if not skip_inference:
+        with console.status("[bold green]Stage 3/3:[/bold green] Architecture Inference..."):
+            engine = InferenceEngine(akg, repo_path)
+            akg = engine.run()
+
+    graph_path = config.output_path("architecture_graph.json")
+    save_graph(akg, graph_path)
+
+    # --- Summary ---
+    console.print(f"\n[bold green]✓[/bold green] Analysis complete\n")
+    console.print(f"  [dim]repository_inventory.json[/dim] → {inv_path}")
+    console.print(f"  [dim]architecture_graph.json[/dim]  → {graph_path}")
+    console.print(f"\n  Nodes: [bold]{akg.node_count}[/bold]  Edges: [bold]{akg.edge_count}[/bold]\n")
+
+
+def _print_inventory_summary(inventory: object) -> None:
+    from system_design.discovery.models import RepositoryInventory
+
+    if not isinstance(inventory, RepositoryInventory):
+        return
+
+    table = Table(title="Repository Inventory", show_header=True, header_style="bold cyan")
+    table.add_column("Property", style="dim")
+    table.add_column("Value")
+
+    table.add_row("Name", inventory.repository_name)
+    table.add_row("Primary Language", inventory.primary_language)
+    table.add_row("Total Files", str(inventory.total_files))
+    table.add_row(
+        "Languages",
+        ", ".join(f"{ls.language}({ls.file_count})" for ls in inventory.languages[:5]),
+    )
+    table.add_row(
+        "Frameworks",
+        ", ".join(f.framework for f in inventory.frameworks) or "None detected",
+    )
+    table.add_row(
+        "Package Managers",
+        ", ".join(p.manager for p in inventory.package_managers) or "None detected",
+    )
+    table.add_row("Has Tests", "✓" if inventory.has_tests else "✗")
+    table.add_row("Has CI", "✓" if inventory.has_ci else "✗")
+
+    console.print(table)
+    console.print()

system_design/cli/main.py

@@ -0,0 +1,79 @@
+"""system-design CLI entrypoint."""
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from system_design.cli.commands.analyze import analyze_command
+
+app = typer.Typer(
+    name="system-design",
+    help="system-design — Architecture Intelligence Engine",
+    add_completion=False,
+    rich_markup_mode="rich",
+)
+
+console = Console()
+
+
+@app.command("analyze")
+def analyze(
+    repo_path: str = typer.Argument(..., help="Path to repository"),
+    output_dir: str = typer.Option(".system-design", "--output", "-o"),
+    verbose: bool = typer.Option(False, "--verbose", "-v"),
+    skip_inference: bool = typer.Option(False, "--no-inference"),
+) -> None:
+    """Analyze a repository: Discovery → Graph → Inference."""
+    from pathlib import Path
+    analyze_command(
+        repo_path=Path(repo_path),
+        output_dir=Path(output_dir),
+        verbose=verbose,
+        skip_inference=skip_inference,
+    )
+
+
+@app.command("visualize")
+def visualize(
+    graph_path: str = typer.Argument(..., help="Path to architecture_graph.json"),
+    output: str = typer.Option("architecture.html", "--output", "-o", help="Output HTML file path"),
+) -> None:
+    """Generate a standalone 3D interactive architecture visualisation."""
+    from pathlib import Path
+    from system_design.visualization.threejs_generator import generate_html_from_file
+
+    src = Path(graph_path)
+    if not src.exists():
+        console.print(f"[bold red]Error:[/bold red] File not found: {graph_path}")
+        raise typer.Exit(code=1)
+
+    out = generate_html_from_file(src, Path(output))
+    console.print(f"[bold green]✓[/bold green] 3D visualisation written to [bold]{out}[/bold]")
+
+
+@app.command("ai-analyze")
+def ai_analyze(
+    repo_path: str = typer.Argument(..., help="Path to repository"),
+    output_dir: str = typer.Option(".system-design", "--output", "-o"),
+    model: str = typer.Option("claude-opus-4-6", "--model", "-m", help="Claude model to use"),
+    verbose: bool = typer.Option(False, "--verbose", "-v"),
+) -> None:
+    """Full AI pipeline: Scan → Claude Analysis → 3D System Design."""
+    from pathlib import Path
+    from system_design.cli.commands.ai_analyze import ai_analyze_command
+    ai_analyze_command(
+        repo_path=Path(repo_path),
+        output_dir=Path(output_dir),
+        model=model,
+        verbose=verbose,
+    )
+
+
+@app.command("version")
+def version() -> None:
+    """Show version."""
+    console.print("[bold blue]system-design[/bold blue] v0.1.0 — Architecture Intelligence Engine")
+
+
+if __name__ == "__main__":
+    app()

system_design/core/config.py

@@ -0,0 +1,26 @@
+"""system-design core configuration."""
+from __future__ import annotations
+
+from pathlib import Path
+from pydantic import BaseModel, Field
+
+
+class ZEAConfig(BaseModel):
+    """Global system-design configuration."""
+
+    output_dir: Path = Field(default=Path(".system-design"), description="Output directory for artifacts")
+    verbose: bool = False
+    max_file_size_kb: int = 512  # Skip files larger than this
+    exclude_dirs: list[str] = Field(
+        default_factory=lambda: [
+            ".git", ".hg", ".svn",
+            "node_modules", "__pycache__", ".venv", "venv", "env",
+            ".tox", "dist", "build", ".eggs", "*.egg-info",
+            ".mypy_cache", ".ruff_cache", ".pytest_cache",
+            "coverage", ".coverage",
+        ]
+    )
+
+    def output_path(self, filename: str) -> Path:
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        return self.output_dir / filename