# iamshouvikmitra/bharat-courts architecture

> Architecture diagram of the GitHub repository iamshouvikmitra/bharat-courts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iamshouvikmitra/bharat-courts
- Repository: https://github.com/iamshouvikmitra/bharat-courts

## Overview

1. **Repository shape**
   - This is an async Python SDK, not a server app.
   - Public entrypoint is `src/bharat_courts/__init__.py`, which re-exports the main clients, registry helpers, models, and the federated `Judgments` facade.
   - The package is organized by source/portal, with a shared core for models, config, HTTP, and court metadata.

2. **Core domain layer**
   - `models.py` defines the shared dataclasses returned by all APIs: `Court`, `CaseInfo`, `CaseOrder`, `CauseListPDF`, `CauseListEntry`, `JudgmentResult`, and `SearchResult`.
   - These models are the normalization boundary: portal-specific parsers map heterogeneous HTML/JSON into these common shapes so downstream code can ignore source differences.
   - `courts.py` is the static registry for Supreme Court + High Courts, including codes used by different portals and CNR prefix inference.

3. **Shared runtime/config layer**
   - `config.py` centralizes environment-driven settings via the `BHARAT_COURTS_*` prefix.
   - `http.py` provides the shared async HTTP client with rate limiting, retries, and timeout behavior.
   - This shared HTTP layer is used by all live portals and likely governs the SDK’s request pacing and failure handling.

4. **Federated judgment lookup**
   - `facade.py` implements `Judgments`, the main “search one thing, route to the right backend” subsystem.
   - It owns both the archive client and the live judgment-search client, decides backend based on query shape, and returns unified `Judgment` objects.
   - Important boundary: this is the only subsystem that mixes live + archive judgment sources.

5. **Live High Court services**
   - `hcservices/` targets `hcservices.ecourts.gov.in`.
   - Flow: client builds endpoint/form payloads → shared HTTP layer sends session-aware requests → parser converts JSON/HTML responses into `CaseInfo`, `CaseOrder`, and `CauseListPDF`.
   - CAPTCHA is part of this portal’s search flows, so the client accepts a `CaptchaSolver` and retries on failure.

6. **District courts portal**
   - `districtcourts/` targets `services.ecourts.gov.in`.
   - Unlike High Courts, discovery is dynamic: state → district → court complex → establishment → case type/court dropdown.
   - The portal returns HTML and requires token/session choreography, so the client’s boundary includes discovery methods plus CAPTCHA-backed search/order/cause-list calls.
   - Parsed output is normalized into `CaseInfo`, `CaseOrder`, `CauseListEntry`, and related data.

7. **Judgments search portal**
   - `judgments/` is the live eCourts judgment-search backend.
   - It supports keyword search, pagination, and bulk PDF download, with CAPTCHA gating and session continuity.
   - Parsers produce `JudgmentResult` plus metadata like CNR, citation, disposal nature, and registration date.
   - This is the live counterpart to the archive for recently delivered judgments and free-text search.

8. **Supreme Court live site**
   - `sci/` targets `www.sci.gov.in`, specifically the homepage “Latest Judgements / Orders” feed and PDF download path.
   - It is intentionally narrow: no CAPTCHA, no full search implementation yet.
   - Output is still normalized into `JudgmentResult`, but the source is a scraped feed rather than a form submission.

9. **Calcutta High Court direct site**
   - `calcuttahc/` is separate from eCourts and talks to the Calcutta HC website directly.
   - It combines case lookup and order retrieval, returning a case-level summary plus a list of `CaseOrder` rows.
   - This subsystem is distinct because it has its own portal behavior, form structure, and richer PDF coverage than the generic eCourts routes.

10. **Historical archive subsystem**
   - `archive/` is the opt-in offline-ish read path over public AWS Open Data buckets for SCI and High Courts.
   - `metadata.py` uses DuckDB over partitioned parquet to query judgment metadata efficiently.
   - `schema.py` maps archive rows into the shared `Judgment` shape.
   - `storage.py` handles PDF retrieval and on-disk caching, including SCI tar extraction and HC single-file fetches.
   - `metadata_cache.py` keeps a local mirrored cache of parquet shards with TTL invalidation.

11. **CAPTCHA strategy boundary**
   - `captcha/` contains a solver interface plus three implementations: manual, OCR-based, and ONNX-based.
   - The live portal clients depend on this abstraction rather than on a specific solver, so CAPTCHA handling is pluggable.
   - This is a key architectural seam: portal clients request a solution; solvers are isolated from portal-specific request logic.

12. **CLI and skill packaging**
   - `cli.py` exposes the SDK as a command-line interface with command groups mirroring the module layout: courts, live portals, archive, and federated find.
   - The `skill/` directory packages an AI-agent skill entrypoint, so the same backend clients can be invoked through assistants like Claude Code or Copilot.
   - This is presentation only; all substantive work still flows through the same clients and shared models.

13. **End-to-end data flow**
   - Typical flow is: user code or CLI → facade or portal client → endpoint builder → shared HTTP client → external portal or archive → parser/schema mapper → shared dataclass model.
   - For live portals, the flow also includes session handling, CAPTCHA solving, and sometimes rotating tokens.
   - For the archive, the flow is metadata query first, then PDF retrieval from cached or remote storage.

14. **Main architectural boundary**
   - The repo is fundamentally split into two backends: **live portals** and **historical archive**.
   - Live portals are mutable, CAPTCHA-heavy, and source-specific.
   - The archive is read-only, queryable via DuckDB, and optimized for bulk retrieval and offline-friendly access.
   - The federated `Judgments` facade sits on top of both and hides this split when a query can be routed automatically.

Main entry points: [`src/bharat_courts/models.py`](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/models.py) (Models), [`src/bharat_courts/http.py`](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/http.py) (HTTP), [`src/bharat_courts/facade.py`](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/facade.py) (Judgments facade), [`src/bharat_courts/__init__.py`](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/__init__.py) (Public API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core"]
  node_public_api["Public API<br/>package export<br/>[__init__.py]"]
  node_models["Models<br/>dataclasses<br/>[models.py]"]
  node_courts["Courts<br/>registry<br/>[courts.py]"]
  node_config["Config<br/>env settings<br/>[config.py]"]
  node_http["HTTP<br/>async client<br/>[http.py]"]
  node_captcha{{"Captcha<br/>solver interface"}}
  node_facade["Judgments facade<br/>federation<br/>[facade.py]"]
end

subgraph group_live["Live portals"]
  node_hcservices_client["HC services<br/>live client<br/>[client.py]"]
  node_hcservices_parser["HC parser<br/>response parser<br/>[parser.py]"]
  node_district_client["District courts<br/>live client<br/>[client.py]"]
  node_district_parser["District parser<br/>response parser<br/>[parser.py]"]
  node_judgments_client["Judgment search<br/>live client<br/>[client.py]"]
  node_judgments_parser["Judgment parser<br/>response parser<br/>[parser.py]"]
  node_sci_client["SCI feed<br/>scraper client<br/>[client.py]"]
  node_sci_parser["SCI parser<br/>response parser<br/>[parser.py]"]
  node_calcutta_client["Calcutta HC<br/>direct site client<br/>[client.py]"]
  node_calcutta_parser["Calcutta parser<br/>response parser<br/>[parser.py]"]
end

subgraph group_archive["Archive"]
  node_archive_client["Archive client<br/>[client.py]"]
  node_archive_metadata[("Archive metadata<br/>duckdb query<br/>[metadata.py]")]
  node_archive_schema["Archive schema<br/>row mapping<br/>[schema.py]"]
  node_archive_storage["Archive storage<br/>pdf cache<br/>[storage.py]"]
end

subgraph group_presentation["Presentation"]
  node_cli["CLI<br/>command line<br/>[cli.py]"]
  node_skill["Skill<br/>assistant package<br/>[SKILL.md]"]
end

node_public_api -->|"re-exports"| node_models
node_public_api -->|"re-exports"| node_courts
node_public_api -->|"re-exports"| node_facade
node_facade -->|"routes to"| node_archive_client
node_facade -->|"routes to"| node_judgments_client
node_facade -->|"returns"| node_models
node_hcservices_client -->|"uses"| node_http
node_hcservices_client -->|"uses"| node_captcha
node_hcservices_client -->|"parses with"| node_hcservices_parser
node_hcservices_parser -->|"maps to"| node_models
node_district_client -->|"uses"| node_http
node_district_client -->|"uses"| node_captcha
node_district_client -->|"parses with"| node_district_parser
node_district_parser -->|"maps to"| node_models
node_judgments_client -->|"uses"| node_http
node_judgments_client -->|"uses"| node_captcha
node_judgments_client -->|"parses with"| node_judgments_parser
node_judgments_parser -->|"maps to"| node_models
node_sci_client -->|"uses"| node_http
node_sci_client -->|"parses with"| node_sci_parser
node_sci_parser -->|"maps to"| node_models
node_calcutta_client -->|"uses"| node_http
node_calcutta_client -->|"parses with"| node_calcutta_parser
node_calcutta_parser -->|"maps to"| node_models
node_archive_client -->|"queries"| node_archive_metadata
node_archive_client -->|"normalizes with"| node_archive_schema
node_archive_client -->|"fetches PDFs"| node_archive_storage
node_archive_metadata -->|"reads"| node_config
node_archive_schema -->|"maps to"| node_models
node_archive_storage -->|"reads"| node_config
node_cli -->|"invokes"| node_public_api
node_skill -->|"describes"| node_public_api
node_config -->|"configures"| node_http
node_courts -->|"supports routing"| node_facade

click node_public_api "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/__init__.py"
click node_models "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/models.py"
click node_courts "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/courts.py"
click node_config "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/config.py"
click node_http "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/http.py"
click node_captcha "https://github.com/iamshouvikmitra/bharat-courts/tree/main/src/bharat_courts/captcha"
click node_facade "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/facade.py"
click node_hcservices_client "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/hcservices/client.py"
click node_hcservices_parser "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/hcservices/parser.py"
click node_district_client "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/districtcourts/client.py"
click node_district_parser "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/districtcourts/parser.py"
click node_judgments_client "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/judgments/client.py"
click node_judgments_parser "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/judgments/parser.py"
click node_sci_client "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/sci/client.py"
click node_sci_parser "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/sci/parser.py"
click node_calcutta_client "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/calcuttahc/client.py"
click node_calcutta_parser "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/calcuttahc/parser.py"
click node_archive_client "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/archive/client.py"
click node_archive_metadata "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/archive/metadata.py"
click node_archive_schema "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/archive/schema.py"
click node_archive_storage "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/archive/storage.py"
click node_cli "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/cli.py"
click node_skill "https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/skill/SKILL.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_api,node_models,node_courts,node_config,node_http,node_captcha,node_facade toneBlue
class node_hcservices_client,node_hcservices_parser,node_district_client,node_district_parser,node_judgments_client,node_judgments_parser,node_sci_client,node_sci_parser,node_calcutta_client,node_calcutta_parser toneAmber
class node_archive_client,node_archive_metadata,node_archive_schema,node_archive_storage toneMint
class node_cli,node_skill toneRose
```

## Components

### Core

Shared models, registry, config, HTTP, and CAPTCHA boundaries

- [Public API](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/__init__.py): package export · Top-level re-exports for clients, models, registry helpers, and federated judgments · `src/bharat_courts/__init__.py`
- [Models](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/models.py): dataclasses · Shared normalized result types used across all backends · `src/bharat_courts/models.py`
- [Courts](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/courts.py): registry · Static court metadata, codes, and CNR prefix inference · `src/bharat_courts/courts.py`
- [Config](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/config.py): env settings · Environment-driven SDK configuration via BHARAT_COURTS_* variables · `src/bharat_courts/config.py`
- [HTTP](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/http.py): async client · Shared async request layer with rate limiting, retries, and timeouts · `src/bharat_courts/http.py`
- [Captcha](https://github.com/iamshouvikmitra/bharat-courts/tree/main/src/bharat_courts/captcha): solver interface · Pluggable CAPTCHA abstraction and implementations · `src/bharat_courts/captcha`
- [Judgments facade](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/facade.py): federation · Routes judgment lookup between live search and archive backends · `src/bharat_courts/facade.py`

### Live portals

Portal-specific async clients and parsers for current court systems

- [HC services](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/hcservices/client.py): live client · High Court eCourts client for case, order, and cause-list flows · `src/bharat_courts/hcservices/client.py`
- [HC parser](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/hcservices/parser.py): response parser · Normalizes hcservices HTML/JSON into shared models · `src/bharat_courts/hcservices/parser.py`
- [District courts](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/districtcourts/client.py): live client · District eCourts client with discovery and session-backed search flows · `src/bharat_courts/districtcourts/client.py`
- [District parser](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/districtcourts/parser.py): response parser · Parses district court HTML into shared case and order models · `src/bharat_courts/districtcourts/parser.py`
- [Judgment search](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/judgments/client.py): live client · Live eCourts judgment search client with pagination and PDF download · `src/bharat_courts/judgments/client.py`
- [Judgment parser](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/judgments/parser.py): response parser · Transforms judgment search responses into unified judgment results · `src/bharat_courts/judgments/parser.py`
- [SCI feed](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/sci/client.py): scraper client · Supreme Court latest judgments and orders feed scraper · `src/bharat_courts/sci/client.py`
- [SCI parser](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/sci/parser.py): response parser · Parses SCI homepage feed and PDF-linked judgment results · `src/bharat_courts/sci/parser.py`
- [Calcutta HC](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/calcuttahc/client.py): direct site client · Direct Calcutta High Court case and order retrieval client · `src/bharat_courts/calcuttahc/client.py`
- [Calcutta parser](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/calcuttahc/parser.py): response parser · Normalizes Calcutta HC responses into case and order data · `src/bharat_courts/calcuttahc/parser.py`

### Archive

Historical judgment metadata and PDF retrieval

- [Archive client](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/archive/client.py): archive client · High-level archive access for metadata lookup and PDF retrieval · `src/bharat_courts/archive/client.py`
- [Archive metadata](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/archive/metadata.py): duckdb query · DuckDB-backed queries over partitioned judgment metadata · `src/bharat_courts/archive/metadata.py`
- [Archive schema](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/archive/schema.py): row mapping · Maps archive rows into the shared judgment shape · `src/bharat_courts/archive/schema.py`
- [Archive storage](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/archive/storage.py): pdf cache · Fetches and caches archive PDFs from remote buckets or local disk · `src/bharat_courts/archive/storage.py`

### Presentation

CLI and skill entrypoints

- [CLI](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/cli.py): command line · Command-line entrypoint mirroring the SDK subsystems · `src/bharat_courts/cli.py`
- [Skill](https://github.com/iamshouvikmitra/bharat-courts/blob/main/src/bharat_courts/skill/SKILL.md): assistant package · Agent skill packaging for assistant-driven use · `src/bharat_courts/skill/SKILL.md`

## Connections

- Public API → Models: re-exports · Makes shared result types available from the package root
- Public API → Courts: re-exports · Exports registry helpers from the package root
- Public API → Judgments facade: re-exports · Exports the federated judgment lookup entrypoint
- Judgments facade → Archive client: routes to · Uses the archive backend when a query fits historical lookup
- Judgments facade → Judgment search: routes to · Uses the live judgment search backend for current search flows
- Judgments facade → Models: returns · Unifies output into shared judgment objects
- HC services → HTTP: uses · Shares the common async request layer
- HC services → Captcha: uses · Plugs in CAPTCHA solving for search flows
- HC services → HC parser: parses with · Converts portal responses into normalized models
- HC parser → Models: maps to · Produces case info, orders, and cause-list PDFs
- District courts → HTTP: uses · Relies on shared HTTP/session handling
- District courts → Captcha: uses · Uses CAPTCHA solving during search and retrieval
- District courts → District parser: parses with · Converts district portal responses into normalized models
- District parser → Models: maps to · Produces case info, orders, and cause-list entries
- Judgment search → HTTP: uses · Shares async transport and pacing behavior
- Judgment search → Captcha: uses · Solves CAPTCHA before search and download calls
- Judgment search → Judgment parser: parses with · Normalizes live judgment search responses
- Judgment parser → Models: maps to · Builds unified judgment result records
- SCI feed → HTTP: uses · Fetches feed and PDFs through the shared HTTP layer
- SCI feed → SCI parser: parses with · Extracts judgments from the SCI feed pages
- SCI parser → Models: maps to · Produces normalized judgment results
- Calcutta HC → HTTP: uses · Uses shared HTTP requests for the direct site
- Calcutta HC → Calcutta parser: parses with · Converts Calcutta HC pages into structured results
- Calcutta parser → Models: maps to · Returns case summaries and order rows
- Archive client → Archive metadata: queries · Looks up judgments through archive metadata search
- Archive client → Archive schema: normalizes with · Maps archive rows into shared judgment objects
- Archive client → Archive storage: fetches PDFs · Retrieves and caches judgment PDFs
- Archive metadata → Config: reads · Uses environment-driven archive settings
- Archive schema → Models: maps to · Conforms archive rows to the shared judgment shape
- Archive storage → Config: reads · Uses runtime settings for cache and source locations
- CLI → Public API: invokes · Commands dispatch into the package root and subsystem clients
- Skill → Public API: describes · Packages the same SDK surface for assistant tooling
- Config → HTTP: configures · Supplies runtime settings used by shared transport
- Courts → Judgments facade: supports routing · Court registry data helps select or interpret backends
