How iamshouvikmitra/bharat-courts works
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: models.py Models · http.py HTTP · facade.py Judgments facade · __init__.py Public API
Components 23
Core
Shared models, registry, config, HTTP, and CAPTCHA boundaries
- Public API · Top-level re-exports for clients, models, registry helpers, and federated judgments
src/bharat_courts/__init__.py - Models · Shared normalized result types used across all backends
src/bharat_courts/models.py - Courts · Static court metadata, codes, and CNR prefix inference
src/bharat_courts/courts.py - Config · Environment-driven SDK configuration via BHARAT_COURTS_* variables
src/bharat_courts/config.py - HTTP · Shared async request layer with rate limiting, retries, and timeouts
src/bharat_courts/http.py - Captcha · Pluggable CAPTCHA abstraction and implementations
src/bharat_courts/captcha - Judgments facade · 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 · High Court eCourts client for case, order, and cause-list flows
src/bharat_courts/hcservices/client.py - HC parser · Normalizes hcservices HTML/JSON into shared models
src/bharat_courts/hcservices/parser.py - District courts · District eCourts client with discovery and session-backed search flows
src/bharat_courts/districtcourts/client.py - District parser · Parses district court HTML into shared case and order models
src/bharat_courts/districtcourts/parser.py - Judgment search · Live eCourts judgment search client with pagination and PDF download
src/bharat_courts/judgments/client.py - Judgment parser · Transforms judgment search responses into unified judgment results
src/bharat_courts/judgments/parser.py - SCI feed · Supreme Court latest judgments and orders feed scraper
src/bharat_courts/sci/client.py - SCI parser · Parses SCI homepage feed and PDF-linked judgment results
src/bharat_courts/sci/parser.py - Calcutta HC · Direct Calcutta High Court case and order retrieval client
src/bharat_courts/calcuttahc/client.py - Calcutta 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 · High-level archive access for metadata lookup and PDF retrieval
src/bharat_courts/archive/client.py - Archive metadata · DuckDB-backed queries over partitioned judgment metadata
src/bharat_courts/archive/metadata.py - Archive schema · Maps archive rows into the shared judgment shape
src/bharat_courts/archive/schema.py - Archive storage · Fetches and caches archive PDFs from remote buckets or local disk
src/bharat_courts/archive/storage.py
Connections 34
- 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