partha

# PARTHA Repository intelligence for private and evolving codebases. ## What it is PARTHA takes a repository revision (imported as ZIP/TAR archive or public GitHub repo) and builds a persistent, immutable snapshot of its structure. From that one snapshot it serves: - **Architecture** — interactive graph of modules and resolved relationships; evidence-cited explanations for supported Python/FastAPI patterns - **Dependency Graph** — declarations from `package.json`, `pyproject.toml`, and `requirements.txt`, with resolved pins from two lockfile formats recorded separately - **Engineering Review** — findings each backed by stored evidence spans; unassessed categories stay visible; no aggregate score or health percentage - **Repository Insights** — counts, ratios, diagnostics, and coverage from the snapshot alone - **Repository Lineage** — repeated imports of the same repository and branch grouped into durable history - **Documentation & Export** — structural documentation plus Review/Documentation/Architecture/Dependencies exported as JSON, Markdown, HTML, or PDF - **Optional AI Context** — per-user provider configuration with encrypted keys and a deployment-owned egress allowlist; providers receive only structural facts and observed paths, never source bytes or line spans The contract is formalised in the [capability matrix](docs/CAPABILITIES.md), generated from the code and drift-checked in CI. Supported facts retain evidence and provenance tied to an exact source location within the analysed revision. ## How it works ``` Import → Analyse → Explore → Export ``` 1. **Import** — upload an archive or import a public GitHub repository over HTTPS. PARTHA stores a file inventory and revision identity. 2. **Analyse** — a durable, cancellable background job runs a bounded extraction pipeline for supported Python and TypeScript/JavaScript constructs, manifests, lockfiles, service interactions, and Docker Compose. 3. **Explore** — inspect Architecture, Dependencies, Engineering Review, Insights, evidence, and lineage. A missing or stale snapshot shows unavailable rather than falling back to a guessed interpretation. 4. **Export** — generate structural documentation or export results through a JSON/Markdown/HTML/PDF pipeline. The intermediate artefact is `ri.v1` — a versioned, sealed snapshot containing facts, evidence, diagnostics, and a canonical hash. Every product surface reads from this shared model; no consumer re-parses the code independently. AI is a downstream consumer of Repository Intelligence, never an independent interpreter. ## Tech stack - **Backend**: Python 3.12–3.13, FastAPI - **Frontend**: Node.js 22, React - **Database**: SQLite (development) - **Worker**: in-process daemon thread (one job at a time) - **AI providers**: optional, configurable with Fernet-encrypted keys and DNS-pinned egress allowlist ## Quick start ```bash git clone https://github.com/Second-Origin/PARTHA.git cd PARTHA # Backend — http://localhost:8000 (OpenAPI at /docs) cd apps/backend python3.13 -m venv .venv && source .venv/bin/activate pip install -e . cd ../.. && npm run dev:backend # Frontend — http://localhost:5173 cd apps/frontend npm ci npm run dev ``` No container runtime or external database is required for local development. No `.env` file is needed. ## Current limitations - Trusted-environment use only — not hardened for broad shared or multi-tenant hosting. - Deep semantic extraction is limited to Python and TypeScript/JavaScript; other languages contribute file inventory only. - Dependency coverage: three manifest formats and two lockfile formats; no transitive resolution, no vulnerability or outdated-version scanning. - Whole-repository analysis per run — no incremental re-analysis. - Lineage preserves revision history but does not diff snapshots, detect renames/moves, or compute historical blast radius. - Optional AI can call an external provider; only local providers keep everything on host. See the [egress policy](docs/security/AI_PROVIDER_EGRESS.md). ## Documentation - [System Overview](docs/architecture/SYSTEM_OVERVIEW.md) - [Repository Intelligence](docs/architecture/REPOSITORY_INTELLIGENCE.md) - [RFC-0001 — ri.v1 contract](docs/architecture/REPOSITORY_INTELLIGENCE_V1_RFC.md) - [RFC-0002 — Repository Lineage](docs/architecture/REPOSITORY_LINEAGE_RFC.md) - [Capability matrix](docs/CAPABILITIES.md) - [Development guide](docs/DEVELOPMENT.md) - [AI provider setup](docs/operations/AI_PROVIDER_SETUP.md) - [Security policy](SECURITY.md) ## License Apache License 2.0 ## Community - [Discord](https://discord.gg/qvk9DcxDA) - [Issues](https://github.com/Second-Origin/PARTHA/issues)