Try the workflow · What works · How it works · Run locally · Limitations · Docs

PARTHA turns a repository revision into one sealed, queryable model and uses it to explain architecture, dependencies, review findings, insights, and documentation without letting each feature invent its own interpretation.

Current stage: advanced prototype / pre-alpha. PARTHA runs locally and its flagship workflow is usable, but it is not a beta, a production SaaS, or a hardened public multi-tenant deployment.

PARTHA is for technical founders, staff and platform engineers, and engineering leads who need an inspectable starting point for understanding a codebase they did not write—or no longer fully trust their mental model of.

From scattered code to shared understanding

Understanding an unfamiliar or fast-moving codebase usually means reconstructing the same facts repeatedly: entry points from folders, dependencies from manifests, boundaries from imports, and risk from partial tooling. Documentation, static analysis, and AI can each build a different private interpretation—and those interpretations drift.

PARTHA takes a different approach. A bounded extraction pipeline turns the selected repository revision into a persistent Repository Intelligence snapshot. Architecture, Dependency Graph, Engineering Review, Insights, Documentation, exports, and optional AI all consume that shared model.

The result is a codebase view that is:

• consistent across surfaces — one stored fact model, not a parser per feature;
• revision-bound — a Git commit or uploaded-archive hash identifies the source;
• inspectable — supported facts carry extractor and source evidence;
• honest about gaps — unavailable or uncomputed assessments stay explicit.

Try the core workflow

For the shortest path to value, run PARTHA locally and use a real repository with Python or TypeScript/JavaScript code.

1. Add a repository. Upload a ZIP, TAR, TAR.GZ, or TGZ archive, or import a public GitHub repository over HTTPS.
2. Run analysis. PARTHA starts a durable, cancellable background job and seals a snapshot for that exact repository revision.
3. Inspect the codebase from several angles.
   • Architecture maps snapshot-backed modules and relationships in an interactive graph.
   • Dependency Graph inventories supported direct declarations and their manifest locations.
   • Engineering Review publishes only findings supported by stored evidence and keeps unassessed categories visible.
   • Insights reports defined snapshot-local counts, ratios, diagnostics, languages, and extractor coverage.
   • Evidence Explorer opens supported findings at the verified source span.
4. Share the result. Generate structural documentation or export Review, Documentation, Architecture, and Dependencies as JSON, Markdown, HTML, or PDF.

Across those surfaces, PARTHA keeps the repository revision, snapshot identity, and canonical graph hash aligned. A missing or stale snapshot produces an unavailable state instead of silently falling back to another interpretation.

What works today

Statuses describe executable behaviour on the current dev branch:

Capability	Assessment	Current boundary
Archive upload and public GitHub import	Implemented	ZIP/TAR-family archives and shallow public GitHub HTTPS clones; size and path-safety limits apply. Private GitHub cloning and other repository hosts are not supported.
Repository explorer	Implemented	Owner-scoped file tree plus bounded text/image preview, binary detection, and truncation.
Authentication and owner isolation	Implemented	Email/password, Argon2, short-lived access tokens, rotating refresh tokens with reuse detection. Protected resources are owner-scoped; non-owner access returns 404.
Analysis lifecycle	Implemented	Database-backed, cancellable job with progress, bounded retry, lease renewal, and stale-worker recovery.
Repository Intelligence	Implemented, limited	Immutable, revision-addressed ri.v1 snapshots with normalized facts, evidence, query APIs, and a total canonical graph hash. Semantic extraction is strongest for supported Python and TypeScript/JavaScript constructs.
Architecture and authentication explanation	Implemented, limited	Interactive snapshot-backed graph. Module/layer classification is heuristic. The cited authentication subgraph covers supported Python/FastAPI patterns only.
Dependency Graph	Implemented, limited	Direct declarations from package.json, requirements.txt, and pyproject.toml, including repeated workspace declarations and exact manifest spans. No lockfiles or transitive resolution.
Engineering Review	Implemented, limited	engineering-review.v2; evidence-addressed findings and explicit category states. No overall score, grade, health percentage, vulnerability result, or generated roadmap.
Repository Insights	Implemented, limited	repository-insights.v1; defined counts, ratios, diagnostics, language breakdowns, and extraction coverage from one snapshot. No change-over-time claims.
Documentation and report export	Implemented, limited	Documentation uses current-revision structural facts. Review, Documentation, Architecture, and Dependencies export through one JSON/Markdown/HTML/PDF pipeline.
AI provider integration	Implemented, limited	Per-user configuration for supported providers, encrypted API keys, and constrained outbound destinations. Free-form answers receive structural facts and observed paths—not source bytes or line spans—and return no automatic citations.
Asynchronous processing	Partially implemented	Analysis runs off the request path. Import, extraction of the initial archive/clone, and file-tree parsing remain synchronous; one in-process worker handles analysis jobs.
Incremental re-analysis and revision comparison	Not implemented / not assessed	The full repository is analysed again; no snapshot-to-snapshot product workflow is available.
Change-impact or blast-radius analysis	Not implemented / not assessed	No product result is emitted.
Vulnerability and outdated-dependency scanning	Not implemented / not assessed	Dependency responses report explicit not_computed states; Review keeps vulnerability scanning not_assessed. No clean bill of health or zero count is fabricated.
Grounded, cited free-form AI answers	Not implemented / not assessed	Provider answers are intentionally uncited because providers do not receive source content or line numbers.

Implemented, limited means the workflow exists but has a disclosed coverage or trust boundary. Partially implemented means only part of the end-to-end behaviour exists. Not implemented / not assessed means PARTHA does not manufacture an answer.

One repository model, many consumers

Repository Intelligence is PARTHA's single repository-understanding boundary. Repository source enters one bounded import and extraction path; product consumers query the resulting sealed snapshot rather than opening files or constructing parallel facts.

ri.v1 is PARTHA's versioned, sealed Repository Intelligence snapshot: the product's single read model. Each immutable snapshot describes one repository at one exact revision and is identified by repository_id, revision, schema_version, producer_version_set, and config_hash; every fact carries a truth class and, where the contract requires it, provenance tied to an exact source location in that stored revision. Architecture, Dependency Graph, Review, Insights, Documentation, Exports, and AI consume the sealed snapshot instead of re-parsing repository files; if the current-revision snapshot is missing or stale, PARTHA reports it as unavailable rather than falling back to a parallel interpretation. The governing contract is the accepted RFC-0001.

flowchart LR
    Input["Repository input<br/>archive · public GitHub"]
    Import["Import<br/>safe storage · revision identity · file inventory"]
    Analyse["Durable analysis<br/>Python · TypeScript/JavaScript · manifests"]
    RI[("Sealed ri.v1 snapshot<br/>facts · evidence · diagnostics · canonical hash")]
    Product["Architecture · Dependencies · Review<br/>Insights · Documentation · Exports"]
    AI["AI provider<br/>optional · structural context only"]

    Input --> Import --> Analyse --> RI --> Product
    RI -.-> AI

Loading

The architectural rule is deliberately strict:

If a feature needs a repository fact, reusable extraction belongs in apps/backend/app/intelligence/. A consumer must never build a second parser. AI is an optional downstream consumer of Repository Intelligence, never an independent interpreter of the repository.

Evidence, provenance, and integrity

PARTHA separates three ideas that are often blurred together:

• Evidence is the stored source artifact supporting a fact, such as a file, declaration, import, route, or configuration entry.
• Provenance records where a supported fact came from: revision, path, line span, extractor, and fact identity.
• Integrity is represented by the snapshot's canonical graph hash and revision manifest. The digest detects content differences inside this deployment; it is not a digital signature or proof of authorship.

Coverage is surface-dependent. Supported Python and TypeScript/JavaScript facts can carry exact spans; Dependency declarations, the authentication explanation, and Review findings expose targeted evidence. Documentation uses structural facts, and free-form AI receives no source bytes or line numbers, so its prose has no automatic citations.

Read Repository Intelligence for the complete extraction boundary and System Overview for the runtime architecture.

Run PARTHA locally

Prerequisites

Tool	Version	Needed for
Python	3.12 or 3.13	Backend
Node.js	22	Frontend and workflow scripts
Git	Recent version	Checkout and public GitHub import
Docker Engine with Compose and buildx plugins	Recent version	One-command full stack

Preferred: start the full stack

With Docker Engine running, build and start the frontend, API, PostgreSQL, and Redis from this checkout:

npm run partha

The command waits for both application services to become healthy, then prints the frontend URL. Open http://localhost:5173, register a local account, add a repository, and start analysis. Press Ctrl+C to stop all four services.

On repeat runs the images are reused from cache, so startup is fast. If you have already built the images once and only want to restart the existing containers without the build step, use:

npm run partha:up

To stop the stack without the interactive Ctrl+C (for example from another terminal), use:

npm run partha:down

PostgreSQL data and imported repository storage persist across ordinary stops and restarts. To permanently delete that local Compose data and return to a clean state, run:

docker compose down -v

Warning: The reset command permanently deletes the Compose database and repository-storage volumes.

Alternative: start services separately

The standalone development configuration uses SQLite, an in-memory rate limiter, and local filesystem storage. It requires Python 3.12 or 3.13 and Node.js 22, but does not require Docker.

1. Start the backend

No .env file is required.

git clone https://github.com/Second-Origin/PARTHA.git
cd PARTHA

cd apps/backend
python3.13 -m venv .venv
source .venv/bin/activate
pip install -e .
cd ../..

npm run dev:backend

The API starts at http://localhost:8000; OpenAPI is at /docs and readiness is at /ready.

2. Start the frontend

In a second terminal:

cd PARTHA
npm ci --prefix apps/frontend
npm run dev:frontend

Open http://localhost:5173, register a local account, add a repository, and start analysis.

Lower-level Compose commands

The launcher wraps these lower-level commands and performs prerequisite and readiness checks. The Compose stack is local development guidance, not production deployment guidance.

npm run docker:config
npm run docker:up

See the AI provider egress policy before configuring any custom or local provider endpoint.

Verification

Run checks relevant to your change:

# Backend (avoids an inherited PYTHONPATH selecting the wrong environment)
cd apps/backend
PYTHONPATH= .venv/bin/python -m pytest
cd ../..

# Frontend
npm --prefix apps/frontend run test
npm run lint:frontend
npm run build:frontend

# Disposable fixtures and browser journeys
npm run test:prototype

# Compose configuration and /ready lifecycle
npm run docker:validate

The prototype browser suite exercises defined Architecture, Engineering Review, Insights, evidence, and responsive-accessibility journeys. Passing it verifies those journeys; it does not imply complete product maturity.

Limitations and security

Product limitations

• Pre-alpha, trusted-environment use. PARTHA has not been operated or hardened as a public multi-tenant service.
• Narrow semantic coverage. Supported Python and TypeScript/JavaScript constructs receive the deepest extraction. Other languages primarily contribute file inventory. Role, module, layer, framework, and entry-point classifications can be heuristic.
• Narrow dependency coverage. Only direct declarations in three manifest formats are extracted. Lockfiles, transitive dependencies, vulnerability scanning, and outdated-version scanning are not implemented.
• No repository evolution workflow. Analysis is whole-repository; incremental analysis, revision comparison, churn/trend analysis, and change impact are unavailable.
• Surface-dependent evidence. A sealed snapshot does not make every product sentence line-cited. In particular, generated structural documentation and free-form AI have stricter evidence limits.
• In-process execution. A daemon worker thread inside the API process handles one analysis job at a time; there is no separate worker service or external job queue.

Security guidance

All non-auth product routes require authentication, repository access is owner-scoped, provider API keys are Fernet-encrypted at rest, and AI egress is validated against a deployment-owned allowlist with DNS pinning. These controls are meaningful, but they are not a claim of production hardening.

Outside development and test, the backend requires:

• AUTH_SECRET_KEY with at least 32 characters;
• AI_ENCRYPTION_KEY containing a valid Fernet key;
• independent network egress controls for AI providers.

Do not expose the development configuration directly to the public internet. Review SECURITY.md and the AI provider egress policy before any shared deployment. Report vulnerabilities privately—never in a public issue.

Documentation and contributing

• Documentation index — current public documentation and reading paths.
• System Overview — components, runtime flow, persistence, and trust boundaries.
• Repository Intelligence — extraction, snapshot, consumer, and evidence rules.
• Accepted ri.v1 RFC — the versioned snapshot contract.
• Backend guide and frontend guide — area-specific setup and commands.
• CONTRIBUTING.md — fork-first workflow, issue claiming, branch conventions, validation, and pull-request requirements.
• CODE_OF_CONDUCT.md — expected conduct.

Before changing analysis, parsing, or AI-grounding behaviour, read Repository Intelligence in full. Current behaviour belongs in documentation; future work belongs in GitHub issues.

License

PARTHA is available under the Apache License 2.0.