# inp-net/churros-online-calendar architecture

> Architecture diagram of the GitHub repository inp-net/churros-online-calendar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/inp-net/churros-online-calendar
- Repository: https://github.com/inp-net/churros-online-calendar

## Overview

Main Components to Include:

##### Client Layer
- Web browsers that interact with the REST API

##### API Layer
- Two main REST endpoints:
- GET /calendars/<calendar_uid>
- POST /register
- This using a rectangle labeled "HTTP Server" (implemented in lib/http)

##### Core Service Layer
- Calendar Generator (lib/calendar)
- ICS Formatter (lib/ics)
- Crypto UID Generator (lib/crypto_rng_uid)

##### Persistence Layer
- Database component (supports both MariaDB and SQLite)
- Connection to Persistence module (lib/persistence)
- Tables for:
- Tokens
- Calendars
- Notes about creation_date and last_access_date fields

- Blue: External clients/services
- Green: API endpoints
- Yellow: Core processing components
- Red: Database/persistence layer

Specific Implementation Details to Highlight:
##### Database Configuration
- Both MariaDB and SQLite options
- DB_URI environment variable configuration
- Default SQLite path (/tmp/test.sql)

##### Data Flow
- Token registration flow:
- Client → POST /register → Token Validation → Database Storage → UID Generation
- Calendar retrieval flow:
- Client → GET /calendars/<uid> → Database Lookup → Calendar Generation → ICS Formatting → Response

##### Limitations Section
- A note about the 10-event limit
- Cleanup considerations for tokens and calendar URLs

Key Architectural Patterns to Emphasize:
##### Layered Architecture
- Clear separation between HTTP, business logic, and persistence layers
- Modular design with separate libraries for distinct functionality

##### RESTful API Design
- Simple, focused endpoints
- Clear separation of concerns

##### Stateless Design
- Calendar state stored in database
- No session management required

##### Notes about automatic updates capability

Level of Detail:
- Database schema in a separate view

Remember to emphasize the project's main purpose: providing an automatically updating calendar feed for Churros events, while maintaining security through token-based authentication and supporting multiple database backends.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Style Definitions
    classDef client fill:#a8d1f0,stroke:#000
    classDef api fill:#90EE90,stroke:#000
    classDef core fill:#FFE5B4,stroke:#000
    classDef db fill:#FFB6C1,stroke:#000
    classDef interface fill:#E6E6FA,stroke:#000

    %% Client Layer
    subgraph Clients
        GC["Google Calendar"]:::client
        OC["Other Calendar Apps"]:::client
        WB["Web Browser"]:::client
    end

    %% API Layer
    subgraph API
        direction TB
        HTTP["HTTP Server"]:::api
        GET["/calendars/<uid>"]:::api
        POST["/register"]:::api
        HTTP --> GET
        HTTP --> POST
    end

    %% Core Service Layer
    subgraph Core
        direction TB
        CG["Calendar Generator"]:::core
        IF["ICS Formatter"]:::core
        UID["Crypto UID Generator"]:::core
        CG --> IF
        UID --> CG
    end

    %% Persistence Layer
    subgraph Database
        direction TB
        DB[("Database\n(MariaDB/SQLite)")]:::db
        PERS["Persistence Module"]:::db
        DBQ["Database Queries"]:::db
        PERS --> DBQ
        DBQ --> DB
    end

    %% Connections
    GC --> GET
    OC --> GET
    WB --> POST
    WB --> GET
    GET --> CG
    POST --> UID
    CG --> PERS
    UID --> PERS

    %% Notes
    subgraph Notes
        direction TB
        N1["10 Event Limit"]
        N2["Auto-updating Feed"]
        N3["Token-based Auth"]
    end

    %% Click Events
    click HTTP "https://github.com/inp-net/churros-online-calendar/blob/main/lib/http/http.ml"
    click CG "https://github.com/inp-net/churros-online-calendar/blob/main/lib/calendar/calendar.ml"
    click IF "https://github.com/inp-net/churros-online-calendar/blob/main/lib/ics/ics.ml"
    click UID "https://github.com/inp-net/churros-online-calendar/blob/main/lib/crypto_rng_uid/crypto_rng_uid.ml"
    click PERS "https://github.com/inp-net/churros-online-calendar/blob/main/lib/persistence/persistence.ml"
    click DBQ "https://github.com/inp-net/churros-online-calendar/blob/main/lib/persistence/queries.ml"
    click WB "https://github.com/inp-net/churros-online-calendar/blob/main/public/index.html"

    %% Legend
    subgraph Legend
        L1["Client Components"]:::client
        L2["API Components"]:::api
        L3["Core Services"]:::core
        L4["Database Components"]:::db
    end
```
