# loireman/nau-timetable architecture

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

- Interactive diagram: https://gitdiagram.com/loireman/nau-timetable
- Repository: https://github.com/loireman/nau-timetable

## Overview

##### Project Type and Purpose
- This is a full-stack monolithic web application (Laravel + Inertia/React) that exposes:
- A browser-based UI (public pages + authenticated user profile + admin panel)
- A versioned JSON REST API (`/api/v1/...`) for timetable lookup and parsing
- A Telegram bot integration (Nutgram) for chat-based timetable queries
- Background/console jobs (schedule notifications, parsers)

##### High-Level Components
A. Client Tier
- Web Browser
- Public SPA pages (Welcome, Timetable lookup, Auth via Google, Profile)
- Admin SPA pages (CRUD for users, roles, permissions, departments, streams, groups, timetables)
- Built with React + Inertia (resources/js → public/build)
- Telegram Bot
- Long-polling/webhook listener using Nutgram
- Commands `/start`, `/today`, `/tomorrow`, `/selectgroup`, etc.

B. Application Server Tier
- Laravel MVC Core (app/Http/Controllers)
- Auth controllers (session, registration, password reset, email verification)
- Admin controllers (Config, Department, Group, Permission, Role, Stream, Timetable, User)
- API controllers (Department, Search, Parse, Google socialite callback)
- Telegram controllers (StartConversation, Timetables)
- Business logic layer
- app/Actions for encapsulating create/update user logic and other domain tasks
- Middleware
- Authentication, authorization (Spatie permissions), CSRF, Inertia request handling
- Console/Jobs
- Scheduled commands (SendScheduledTimetableNotifications)
- Artisan tasks for parsing and seeding

C. Persistence and Infrastructure
- MySQL Database (tables: users, password_resets, personal_access_tokens, permissions, roles, settings, departments, streams, groups, timetables, tguser_group_relations)
- Cache/Session store (file or Redis if configured)
- File storage (local disk for uploads/caches)
- Queue (default database or Redis) for background jobs
- External services
- Google OAuth (config/services.php)
- Telegram Bot API (config/nutgram.php)

##### Relationships and Data Flow
- Web browser → HTTP(S) → Laravel routes (web.php, auth.php, telegram.php) → Controllers → Models → DB → Controllers → Inertia responses / Blade templates → React components
- React components dispatch actions (Inertia visits) and render server-returned props
- API clients → HTTP(S) → routes/api.php → API Controllers → JSON responses
- Telegram webhook/poller → Telegram controllers → Actions/Models → Telegram API (sendMessage, etc.)
- Scheduler (cron → php artisan schedule:run) → Console Kernel → Scheduled Tasks → Notifications via email/Telegram

##### Architectural Patterns and Principles
- MVC on the server side (Models, Views via Inertia/Blade, Controllers)
- CQRS-style separation: Controllers orchestrate Actions for business logic
- Inertia as a thin adapter turning server responses into SPA navigation
- PSR-4 autoloading, Service Providers for bootstrapping (app/Providers)
- Layered: HTTP layer, Application layer (Actions), Domain layer (Models), Infrastructure layer (DB, queue, external APIs)

- Use two consumer lanes on the left: “Web Client” and “Telegram Bot.”
- HTTP Layer (routes → Controllers → Middleware)
- Application Layer (Actions, Services)
- Domain Layer (Eloquent Models)
- Console Layer (Scheduled Commands)
- Below it, show “MySQL Database” and “Cache/Queue Store.”
- On the right, external integrations: “Google OAuth,” “Telegram API.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer Lanes
    subgraph "Web Client" 
        Browser["Browser (React + Inertia SPA)"]:::client
        click Browser "https://github.com/loireman/nau-timetable/tree/main/resources/js/"
    end

    subgraph "Telegram Bot"
        Bot["Telegram Bot (Nutgram)"]:::client
        click Bot "https://github.com/loireman/nau-timetable/blob/main/routes/telegram.php"
    end

    %% Laravel Monolith
    subgraph "Laravel Monolith" 
        subgraph "HTTP/API Layer"
            WebRoutes["routes/web.php"]:::layer
            click WebRoutes "https://github.com/loireman/nau-timetable/blob/main/routes/web.php"
            AuthRoutes["routes/auth.php"]:::layer
            click AuthRoutes "https://github.com/loireman/nau-timetable/blob/main/routes/auth.php"
            ApiRoutes["routes/api.php"]:::layer
            click ApiRoutes "https://github.com/loireman/nau-timetable/blob/main/routes/api.php"
            Controllers["Controllers (app/Http/Controllers/)"]:::layer
            click Controllers "https://github.com/loireman/nau-timetable/tree/main/app/Http/Controllers/"
        end
        subgraph "Application Layer"
            Actions["Actions (app/Actions/)"]:::layer
            click Actions "https://github.com/loireman/nau-timetable/tree/main/app/Actions/"
        end
        subgraph "Domain Layer"
            Models["Models (app/Models/)"]:::layer
            click Models "https://github.com/loireman/nau-timetable/tree/main/app/Models/"
        end
        subgraph "Console Layer"
            Console["Console & Jobs"]:::layer
            click Console "https://github.com/loireman/nau-timetable/blob/main/app/Console/Kernel.php"
        end
    end

    %% Persistence & Infrastructure
    subgraph "Persistence & Infrastructure"
        DB["MySQL Database"]:::persistence
        click DB "https://github.com/loireman/nau-timetable/tree/main/database/migrations/"
        CacheQueue["Cache/Queue Store"]:::persistence
        click CacheQueue "https://github.com/loireman/nau-timetable/blob/main/config/cache.php"
        Cron["Cron Scheduler"]:::persistence
        click Cron "https://github.com/loireman/nau-timetable/blob/main/app/Console/Kernel.php"
    end

    %% External Services
    subgraph "External Services"
        Google["Google OAuth"]:::external
        click Google "https://github.com/loireman/nau-timetable/blob/main/config/services.php"
        TelegramAPI["Telegram API"]:::external
        click TelegramAPI "https://github.com/loireman/nau-timetable/blob/main/config/nutgram.php"
    end

    %% Relationships
    Browser -->|"HTTP/HTTPS"| WebRoutes
    Bot -->|"Webhook/Long-polling"| Controllers
    WebRoutes --> Controllers
    AuthRoutes --> Controllers
    ApiRoutes --> Controllers
    Controllers -->|"invoke"| Actions
    Actions -->|"manipulate"| Models
    Models -->|"SQL"| DB
    Controllers -->|"render/Inertia"| Browser
    Controllers -->|"sendMessage"| TelegramAPI
    Cron -->|"schedule:run"| Console
    Console -->|"dispatch"| Actions
    CacheQueue -->|"Redis/DB"| Console

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef layer fill:#DFF2BF,stroke:#4F8A10,color:#4F8A10;
    classDef persistence fill:#FFE0B2,stroke:#E65100,color:#E65100;
    classDef external fill:#E1BEE7,stroke:#6A1B9A,color:#6A1B9A;
```
