How loireman/nau-timetable works
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.”