# duelitdev/ezneis architecture

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

- Interactive diagram: https://gitdiagram.com/duelitdev/ezneis
- Repository: https://github.com/duelitdev/ezneis

## Overview

##### Project type and purpose
- ezneis is an open‑source Python client library (wrapper) for the NEIS Open API, providing both synchronous and asynchronous interfaces.
- Its goal is to fetch school data (info, schedules, meals, etc.) from the NEIS REST endpoints, parse it into rich Python objects, and support lazy loading, caching, and session management.

##### File structure
Top‑level:
- ezneis/                # Main package
– __init__.py          # Entry points (get_school, get_schools, async variants)
– data/                # Domain orchestrators for each API category (school, synchronous vs asynchronous)
– http/                # HTTP clients and common code for sync (requests) and async (aiohttp)
– parsers/             # Routines to parse JSON/XML responses into primitive dicts
– models/              # Domain model classes (SchoolInfo, Schedule, Meal, etc.)
– utils/               # Caching, region lookup, session manager (shared state, lazy loading)
– wrappers/            # High‑level facade functions for sync and async
– exceptions.py        # Custom error types
- tests/                 # Unit tests for wrappers
- build.sh, pyproject.toml, requirements.txt

##### Key insights from README
- Dual‑mode operation (sync & asyncio).
- All data parsed into appropriate types.
- Lazy loading: data attributes load only when accessed.
- Dependencies: requests (sync), aiohttp (+ aiodns optional).

a. Main components:
1. User Application
2. Sync Wrapper Layer (ezneis.wrappers.synchronous)
3. Async Wrapper Layer (ezneis.wrappers.asynchronous)
4. Data Orchestrators (ezneis.data.school, common logic for each domain)
5. HTTP Client Modules
– Sync HTTP (ezneis.http.synchronous using requests)
– Async HTTP (ezneis.http.asynchronous using aiohttp)
6. Parser Modules (ezneis.parsers.*)
7. Domain Models (ezneis.models.*)
8. Utilities
– Session Manager
– Caches
– Region Resolver
9. External NEIS Open API Endpoint
10. Exceptions (error handling path)

b. Relationships & interactions:
- The User calls get_* or get_*_async (Wrapper Layer).
- The Wrapper calls the Data Orchestrator for the requested domain (e.g., school).
- The Orchestrator uses the appropriate HTTP Client (sync vs async) to send requests to the NEIS API.
- HTTP responses flow back to the orchestrator, which invokes Parser modules to convert raw payload to Python primitives.
- Parsed data is instantiated into Domain Models.
- Lazy attributes trigger more HTTP calls via Utilities (Session Manager & Caches) as needed.
- Exceptions raised at any stage bubble up to the user.

c. Architectural patterns & principles:
- Facade Pattern: wrappers provide a simple API hiding complexity.
- Strategy Pattern: sync vs async HTTP strategies.
- Lazy Loading: models defer sub‑resource fetch until property access.
- Separation of Concerns: HTTP, parsing, modeling, caching are modular.

d. Key technologies & libraries:
- requests for synchronous HTTP
- aiohttp (plus optional aiodns) for asynchronous HTTP
- asyncio for event loop and coroutines
- pytest for testing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point
    User["User Application"]:::external

    subgraph "Facade Layer (Wrappers)"
        SyncWrapper["ezneis.wrappers.synchronous"]:::facade
        AsyncWrapper["ezneis.wrappers.asynchronous"]:::facade
    end

    subgraph "Data Orchestrators"
        SyncData["ezneis.data.school.synchronous"]:::data
        AsyncData["ezneis.data.school.asynchronous"]:::data
        CommonData["ezneis.data.school.common"]:::data
    end

    subgraph "HTTP Layer"
        HTTPCommon["ezneis.http.common"]:::http
        SyncHTTP["ezneis.http.synchronous (requests)"]:::http
        AsyncHTTP["ezneis.http.asynchronous (aiohttp)"]:::http
    end

    subgraph "Parsers"
        ParserCommon["ezneis.parsers.common"]:::parser
        ParserSI["ezneis.parsers.school_info"]:::parser
        ParserSch["ezneis.parsers.schedule"]:::parser
        ParserMeal["ezneis.parsers.meal"]:::parser
        ParserTT["ezneis.parsers.time_table"]:::parser
        ParserCR["ezneis.parsers.classroom"]:::parser
        ParserDept["ezneis.parsers.department"]:::parser
        ParserLR["ezneis.parsers.lecture_room"]:::parser
        ParserMajor["ezneis.parsers.major"]:::parser
    end

    subgraph "Domain Models"
        ModelCommon["ezneis.models.common"]:::model
        ModelSI["ezneis.models.school_info"]:::model
        ModelSch["ezneis.models.schedule"]:::model
        ModelMeal["ezneis.models.meal"]:::model
        ModelTT["ezneis.models.time_table"]:::model
        ModelCR["ezneis.models.classroom"]:::model
        ModelDept["ezneis.models.department"]:::model
        ModelLR["ezneis.models.lecture_room"]:::model
        ModelMajor["ezneis.models.major"]:::model
    end

    subgraph "Utilities"
        SessionMgr["ezneis.utils.session_manager"]:::util
        Caches["ezneis.utils.caches"]:::util
        Region["ezneis.utils.region"]:::util
    end

    Exceptions["ezneis.exceptions"]:::exception

    ExternalAPI["NEIS Open API Endpoint"]:::external

    %% Relationships
    User -->|uses sync API| SyncWrapper
    User -->|uses async API| AsyncWrapper

    SyncWrapper -->|calls| SyncData
    AsyncWrapper -->|calls| AsyncData

    SyncData -->|shared logic| CommonData
    AsyncData -->|shared logic| CommonData

    SyncData -->|HTTP request| SyncHTTP
    AsyncData -->|HTTP request| AsyncHTTP

    SyncHTTP -->|common helpers| HTTPCommon
    AsyncHTTP -->|common helpers| HTTPCommon

    SyncHTTP -->|requests| ExternalAPI
    AsyncHTTP -->|aiohttp| ExternalAPI

    ExternalAPI -->|response| SyncHTTP
    ExternalAPI -->|response| AsyncHTTP

    SyncHTTP -->|raw data| ParserCommon
    ParserCommon -->|delegate| ParserSI
    ParserCommon -->|delegate| ParserSch
    ParserCommon -->|delegate| ParserMeal
    ParserCommon -->|delegate| ParserTT
    ParserCommon -->|delegate| ParserCR
    ParserCommon -->|delegate| ParserDept
    ParserCommon -->|delegate| ParserLR
    ParserCommon -->|delegate| ParserMajor

    ParserSI -->|primitives| ModelSI
    ParserSch -->|primitives| ModelSch
    ParserMeal -->|primitives| ModelMeal
    ParserTT -->|primitives| ModelTT
    ParserCR -->|primitives| ModelCR
    ParserDept -->|primitives| ModelDept
    ParserLR -->|primitives| ModelLR
    ParserMajor -->|primitives| ModelMajor

    ModelSI -->|"lazy load"| SessionMgr
    ModelSch -->|"lazy load"| SessionMgr
    ModelMeal -->|"lazy load"| SessionMgr
    SessionMgr -->|caching| Caches
    SessionMgr -->|region lookup| Region

    %% Exception flows
    SyncWrapper -->|errors| Exceptions
    AsyncWrapper -->|errors| Exceptions
    SyncData -->|errors| Exceptions
    AsyncData -->|errors| Exceptions
    HTTPCommon -->|errors| Exceptions
    ParserCommon -->|errors| Exceptions
    ModelCommon -->|errors| Exceptions

    %% User final output
    ModelSI -->|returned| User
    ModelSch -->|returned| User
    ModelMeal -->|returned| User
    ModelTT -->|returned| User
    ModelCR -->|returned| User
    ModelDept -->|returned| User
    ModelLR -->|returned| User
    ModelMajor -->|returned| User

    %% Click Events
    click SyncWrapper "https://github.com/duelitdev/ezneis/blob/main/ezneis/wrappers/synchronous.py"
    click AsyncWrapper "https://github.com/duelitdev/ezneis/blob/main/ezneis/wrappers/asynchronous.py"
    click SyncData "https://github.com/duelitdev/ezneis/blob/main/ezneis/data/school/synchronous.py"
    click AsyncData "https://github.com/duelitdev/ezneis/blob/main/ezneis/data/school/asynchronous.py"
    click CommonData "https://github.com/duelitdev/ezneis/blob/main/ezneis/data/school/common.py"
    click SyncHTTP "https://github.com/duelitdev/ezneis/blob/main/ezneis/http/synchronous.py"
    click AsyncHTTP "https://github.com/duelitdev/ezneis/blob/main/ezneis/http/asynchronous.py"
    click HTTPCommon "https://github.com/duelitdev/ezneis/blob/main/ezneis/http/common.py"
    click ParserCommon "https://github.com/duelitdev/ezneis/blob/main/ezneis/parsers/common.py"
    click ParserSI "https://github.com/duelitdev/ezneis/blob/main/ezneis/parsers/school_info.py"
    click ParserSch "https://github.com/duelitdev/ezneis/blob/main/ezneis/parsers/schedule.py"
    click ParserMeal "https://github.com/duelitdev/ezneis/blob/main/ezneis/parsers/meal.py"
    click ParserTT "https://github.com/duelitdev/ezneis/blob/main/ezneis/parsers/time_table.py"
    click ParserCR "https://github.com/duelitdev/ezneis/blob/main/ezneis/parsers/classroom.py"
    click ParserDept "https://github.com/duelitdev/ezneis/blob/main/ezneis/parsers/department.py"
    click ParserLR "https://github.com/duelitdev/ezneis/blob/main/ezneis/parsers/lecture_room.py"
    click ParserMajor "https://github.com/duelitdev/ezneis/blob/main/ezneis/parsers/major.py"
    click ModelCommon "https://github.com/duelitdev/ezneis/blob/main/ezneis/models/common.py"
    click ModelSI "https://github.com/duelitdev/ezneis/blob/main/ezneis/models/school_info.py"
    click ModelSch "https://github.com/duelitdev/ezneis/blob/main/ezneis/models/schedule.py"
    click ModelMeal "https://github.com/duelitdev/ezneis/blob/main/ezneis/models/meal.py"
    click ModelTT "https://github.com/duelitdev/ezneis/blob/main/ezneis/models/time_table.py"
    click ModelCR "https://github.com/duelitdev/ezneis/blob/main/ezneis/models/classroom.py"
    click ModelDept "https://github.com/duelitdev/ezneis/blob/main/ezneis/models/department.py"
    click ModelLR "https://github.com/duelitdev/ezneis/blob/main/ezneis/models/lecture_room.py"
    click ModelMajor "https://github.com/duelitdev/ezneis/blob/main/ezneis/models/major.py"
    click SessionMgr "https://github.com/duelitdev/ezneis/blob/main/ezneis/utils/session_manager.py"
    click Caches "https://github.com/duelitdev/ezneis/blob/main/ezneis/utils/caches.py"
    click Region "https://github.com/duelitdev/ezneis/blob/main/ezneis/utils/region.py"
    click Exceptions "https://github.com/duelitdev/ezneis/blob/main/ezneis/exceptions.py"

    %% Styles
    classDef facade fill:#FFD580,stroke:#333,stroke-width:1px
    classDef data fill:#FFCDDD,stroke:#333,stroke-width:1px
    classDef http fill:#C1E1C1,stroke:#333,stroke-width:1px
    classDef parser fill:#B0E0E6,stroke:#333,stroke-width:1px
    classDef model fill:#E6E6FA,stroke:#333,stroke-width:1px
    classDef util fill:#FFDEAD,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef exception fill:#F4C2C2,stroke:#333,stroke-width:1px
```
