# openjustice-in/ecourts architecture

> Architecture diagram of the GitHub repository openjustice-in/ecourts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openjustice-in/ecourts
- Repository: https://github.com/openjustice-in/ecourts

## Overview

##### Project type and purpose
- This is a Python-based information-retrieval toolkit (a CLI/library) for bulk fetching and parsing case data from the ECourts website (hcservices.ecourts.gov.in).
- It exposes both a command-line interface (`ecourts` CLI commands) and a programmatic API (`ecourts.ECourt` class).

##### File structure
- Top-level modules:
- ecourts/cli — CLI entrypoints and argument parsing
- ecourts/ecourt.py — core HTTP client (“ECourt” class)
- ecourts/captcha.py — single-threaded captcha handling
- ecourts/parsers — HTML→domain object parsing logic
- ecourts/entities — domain models (Case, Order, Hearing, etc.)
- ecourts/storage.py — local caching/persistence of fetched data
- courts.csv — static metadata: list of known courts & state codes
- pyproject.toml / setup info defines packaging; GitHub workflows define tests, publishing, docs.

##### README for additional insights
- Purpose: fetch lists of cases, case-details, cause-lists, orders/judgements
- Core abstractions: ECourt (handles HTTP, retries, rate-limiting), Court (metadata), Entities for domain objects
- Guiding principles: single-threaded, polite retries, use ISO-3166 codes

##### Main components
a. Components
1. CLI Layer („ecourts“ commands)
2. ECourt client
3. Captcha handler
4. HTTP/Network interface (Requests library)
5. External ECourts Service (hcservices.ecourts.gov.in)
6. Parsers (HTML → Entities)
7. Domain Entities (Case, Order, Hearing, etc.)
8. Storage layer (local file or in-memory cache; YAML/JSON)
9. Static court metadata (courts.csv)
b. Relationships & interactions
- User invokes CLI → CLI Layer calls ECourt API
- ECourt orchestrates:
– Load metadata (courts.csv) → pick correct state/court code
– Perform HTTP request(s) via HTTP/Network → External ECourts Service
– If Captcha challenge arises → Captcha handler intervenes → resume HTTP requests
– Receive raw HTML/JSON → dispatch to appropriate Parser
– Parser builds Domain Entities
– Entities are optionally persisted via Storage
– CLI or calling code receives Entities for display or further processing
c. Architectural patterns / design principles
- Single-responsibility: separate CLI, HTTP client, captcha logic, parsing, domain modelling, storage
- Layered architecture: Presentation (CLI/API) → Application (ECourt) → Infrastructure (HTTP, Storage)
- Domain-driven design: Entities layer encapsulates legal concepts
- Polite HTTP client: rate-limit, retry, backoff
d. Key technologies / libraries
- Python 3.x, Click or argparse (CLI)
- requests (HTTP) or similar
- BeautifulSoup / lxml (HTML parsing)
- PyYAML or JSON (storage serialization)
- pytest / vcrpy (tests and cassettes)

##### Essential details to capture
- Single-threaded, polite-HTTP pattern (retry/backoff)
- Captcha component inserted in the HTTP flow
- Clear separation of concerns (parsing vs. domain vs. I/O)
- Static metadata lookup (courts.csv) as part of request preparation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        CLI["CLI Layer"]:::presentation
        API["Library API"]:::presentation
    end

    %% Core Logic
    subgraph "Core Logic"
        ECourt["ECourt Client"]:::core
        Captcha["Captcha Handler"]:::core
        Parsers["Parser Module"]:::core
        Entities["Domain Entities"]:::core
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        HTTP["HTTP/Network Interface"]:::infra
        Storage["Storage Layer"]:::infra
        Meta["Static Court Metadata"]:::infra
    end

    %% External Service
    External["External ECourts Service"]:::external

    %% Connections
    CLI -->|"invoke"| ECourt
    API -->|"call ECourt()"| ECourt
    ECourt -->|"load metadata"| Meta
    ECourt -->|"HTTP requests"| HTTP
    HTTP -->|"fetch HTML/JSON"| External
    External -->|"response"| HTTP
    HTTP -->|"captcha challenge"| Captcha
    Captcha -->|"solve & retry"| HTTP
    ECourt -->|"dispatch HTML"| Parsers
    Parsers -->|"build entities"| Entities
    Entities -->|"persist"| Storage
    ECourt -->|"return entities"| CLI
    ECourt -->|"return entities"| API

    %% Click Events
    click CLI "https://github.com/openjustice-in/ecourts/tree/main/ecourts/cli/"
    click ECourt "https://github.com/openjustice-in/ecourts/blob/main/ecourts/ecourt.py"
    click Captcha "https://github.com/openjustice-in/ecourts/blob/main/ecourts/captcha.py"
    click HTTP "https://github.com/openjustice-in/ecourts/blob/main/ecourts/ecourt.py"
    click Parsers "https://github.com/openjustice-in/ecourts/tree/main/ecourts/parsers/"
    click Entities "https://github.com/openjustice-in/ecourts/tree/main/ecourts/entities/"
    click Storage "https://github.com/openjustice-in/ecourts/blob/main/ecourts/storage.py"
    click Meta "https://github.com/openjustice-in/ecourts/blob/main/courts.csv"

    %% Styles
    classDef presentation fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef core fill:#90EE90,stroke:#000,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef external fill:#F5F5F5,stroke:#000,stroke-dasharray:5 5,stroke-width:1px
```
