# bajajharsha/oyez-api architecture

> Architecture diagram of the GitHub repository bajajharsha/oyez-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bajajharsha/oyez-api
- Repository: https://github.com/bajajharsha/oyez-api

## Overview

##### Main Components
- API Client Component: Responsible for making asynchronous calls to the Oyez API using aiohttp, asyncio, and semaphores.
- Data Fetching Module (fetch.py): Fetches case URLs and JSON data from the API endpoints.
- Data Processing & Categorization Module (categorize.py): Processes the fetched JSON data (extracting case facts, audio transcripts, images, and person details) and categorizes the cases into “Resolved” and “UnResolved”.
- Data Storage/Output Component: Represents the file system output structure (as described in the README) which organizes the data into directories such as case details, attorneys, argument transcripts with ‘.mp3’ files, etc.
- Utility/Configuration: Although small, elements like requirements.txt and .gitignore hint at dependency management and versioning best practices.

##### Relationships and Interactions
- The categorize.py module then writes the processed data into the respective directories (Resolved/UnResolved) on the file system.

##### Important Architectural Patterns & Design Principles
- Asynchronous Programming: Emphasize that the project maximizes concurrency via aiohttp and asyncio, reducing wait times during API calls.
- Modular Design: Separate concerns between data fetching and data processing, making the system easier to maintain and extend.
- Directory-based Data Organization: The output file/folder structure is critical and should be captured clearly – explain how each type of file (e.g., transcripts, audio files, profiles) fits into the system.

##### Relevant Technologies and Frameworks
- Python (primary language)
- aiohttp and asyncio for asynchronous API operations
- Built-in libraries for data handling and file I/O operations
- OS file system concepts to manage output directories

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        API["Oyez API Endpoint"]:::external
    end

    %% Data Retrieval Layer
    subgraph "Data Retrieval"
        FETCH["Fetch Module (fetch.py)\\n[Asynchronous API Client using aiohttp & asyncio]"]:::fetchMod
    end

    %% Data Processing Layer
    subgraph "Data Processing"
        CATEGORIZE["Categorize Module (categorize.py)\\n[Process JSON data, extract assets, and assign cases]"]:::processMod
    end

    %% Output Storage Layer
    subgraph "Output Storage"
        RESOLVED["Resolved Cases (Directory)"]:::output
        UNRESOLVED["UnResolved Cases (Directory)"]:::output
    end

    %% Utility/Configuration
    subgraph "Utility/Configuration"
        UTILITY_REQ["requirements.txt"]:::utility
        UTILITY_GIT[".gitignore"]:::utility
    end

    %% Data Flow Connections
    API -->|"fetchCaseURLs"| FETCH
    FETCH -->|"JSONData"| CATEGORIZE
    CATEGORIZE -->|"ProcessedData"| RESOLVED
    CATEGORIZE -->|"ProcessedData"| UNRESOLVED

    %% Click Events for Component Mapping
    click FETCH "https://github.com/bajajharsha/oyez-api/blob/main/src/fetch.py"
    click CATEGORIZE "https://github.com/bajajharsha/oyez-api/blob/main/src/categorize.py"
    click UTILITY_REQ "https://github.com/bajajharsha/oyez-api/blob/main/requirements.txt"
    click UTILITY_GIT "https://github.com/bajajharsha/oyez-api/blob/main/.gitignore"

    %% Styles
    classDef external fill:#fce4ec,stroke:#c2185b,stroke-width:2px;
    classDef fetchMod fill:#e1f5fe,stroke:#0277bd,stroke-width:2px;
    classDef processMod fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;
    classDef output fill:#fff3e0,stroke:#ef6c00,stroke-width:2px;
    classDef utility fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px;
```
