# mati365/librus-api architecture

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

- Interactive diagram: https://gitdiagram.com/mati365/librus-api
- Repository: https://github.com/mati365/librus-api

## Overview

##### Project type and purpose
- This is an open-source Node.js HTTP client library (“librus-api”) that logs in to the Librus/Synergia electronic gradebook, sends requests, parses returned HTML, and exposes domain-specific methods (inbox, homework, absence, calendar, info).
- It is not a full-stack application or service; it’s a reusable SDK published on npm for other Node apps to consume.

##### File structure
- Top-level:
- package.json / package-lock.json – defines dependencies and entry point
- .gitignore, .prettierrc – standard repo configs
- README.md – usage & description
- lib/
- api.js – main class (Librus) that wires everything
- config.js – base URLs, endpoints, auth parameters
- tools.js – shared HTTP/session management & HTML parsing utilities
- resources/ – one module per domain area: absence.js, calendar.js, homework.js, inbox.js, info.js

##### Extract architectural hints from README
- Usage shows a single `Librus` client instance, then calls like `client.inbox.sendMessage(...)`, `client.homework.listSubjects()`, etc.
- Each resource uses HTTP requests + HTML parsing under the covers.

a. Consumer Application (your code)
b. LibrusApi Client Layer (lib/api.js)
c. Configuration Layer (lib/config.js)
d. HTTP & Session Tools (lib/tools.js)
e. Resource Modules (lib/resources/*.js)
f. External Librus/Synergia Web Server

##### Relationships and data flow
- The consumer app calls methods on the LibrusApi instance
- api.js references config.js to assemble URLs and headers
- api.js invokes tools.js to manage login/session cookie & send HTTP requests
- The raw HTML response flows back into a specific resource module (e.g., inbox.js)
- The resource module calls tools.js parsers to turn HTML into JSON data
- Parsed data is returned via Promise to the consumer
- All outbound HTTP calls go to the External Librus/Synergia Web Server

##### Architectural patterns & design principles
- Separation of concerns:
- config.js holds constants
- tools.js holds HTTP/session and parsing logic
- resources/* hold domain-specific workflows and parsers
- api.js composes resources and exposes a unified client interface
- Single-instance client (stateful session via cookies)
- Promise-based asynchronous API

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Consumer Application
    ConsumerApp["Consumer Application"]:::consumer

    %% Package Boundary
    subgraph "librus-api (npm package)"
        direction TB

        %% Core Utilities
        subgraph "Core Utilities"
            direction TB
            Config["config.js"]:::utility
            Tools["tools.js"]:::utility
        end

        %% API Layer
        LibrusAPI["api.js"]:::internal

        %% Resource Modules
        subgraph "Resource Modules"
            direction TB
            Absence["absence.js"]:::module
            Calendar["calendar.js"]:::module
            Homework["homework.js"]:::module
            Inbox["inbox.js"]:::module
            Info["info.js"]:::module
        end
    end

    %% External Server
    ExternalServer["Librus/Synergia Web Server"]:::external

    %% Connections
    ConsumerApp -->|"calls methods"| LibrusAPI
    LibrusAPI -->|"reads URLs & params"| Config
    LibrusAPI -->|"session & HTTP"| Tools
    LibrusAPI -->|"composes resource instance"| Absence
    LibrusAPI -->|"composes resource instance"| Calendar
    LibrusAPI -->|"composes resource instance"| Homework
    LibrusAPI -->|"composes resource instance"| Inbox
    LibrusAPI -->|"composes resource instance"| Info

    Tools -->|"HTTP GET/POST"| ExternalServer
    ExternalServer -->|"raw HTML"| Tools

    Tools -->|"provides HTML payload"| Absence
    Tools -->|"provides HTML payload"| Calendar
    Tools -->|"provides HTML payload"| Homework
    Tools -->|"provides HTML payload"| Inbox
    Tools -->|"provides HTML payload"| Info

    Absence -->|"parse HTML"| Tools
    Calendar -->|"parse HTML"| Tools
    Homework -->|"parse HTML"| Tools
    Inbox -->|"parse HTML"| Tools
    Info -->|"parse HTML"| Tools

    Absence -->|"return JSON"| LibrusAPI
    Calendar -->|"return JSON"| LibrusAPI
    Homework -->|"return JSON"| LibrusAPI
    Inbox -->|"return JSON"| LibrusAPI
    Info -->|"return JSON"| LibrusAPI

    LibrusAPI -->|"resolves Promise with JSON"| ConsumerApp

    %% Click Events
    click LibrusAPI "https://github.com/mati365/librus-api/blob/master/lib/api.js"
    click Config "https://github.com/mati365/librus-api/blob/master/lib/config.js"
    click Tools "https://github.com/mati365/librus-api/blob/master/lib/tools.js"
    click Absence "https://github.com/mati365/librus-api/blob/master/lib/resources/absence.js"
    click Calendar "https://github.com/mati365/librus-api/blob/master/lib/resources/calendar.js"
    click Homework "https://github.com/mati365/librus-api/blob/master/lib/resources/homework.js"
    click Inbox "https://github.com/mati365/librus-api/blob/master/lib/resources/inbox.js"
    click Info "https://github.com/mati365/librus-api/blob/master/lib/resources/info.js"

    %% Styles
    classDef consumer fill:#FFA500,stroke:#333,stroke-width:1px
    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef utility fill:#FFFACD,stroke:#333,stroke-width:1px
    classDef module fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef external fill:#98FB98,stroke:#333,stroke-width:1px
```
