# elan47/tirukkurals architecture

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

- Interactive diagram: https://gitdiagram.com/elan47/tirukkurals
- Repository: https://github.com/elan47/tirukkurals

## Overview

##### Project type and purpose
- It’s a **full-stack Single Page Application** (SPA) for browsing and listening to Tirukkural couplets.
- Backend: Laravel 7.x (MVC + REST API), Eloquent ORM, migration+seeds.
- Frontend: Vue.js 2.x SPA served from Laravel’s public/index.php, built with webpack-mix, Bootstrap 4, Lottie animations.

##### File structure
- **Top-level**:
– /app → Laravel application code (Models, Controllers, Middleware, Resources)
– /config → environment & service configurations (DB, cache, session, mail, sanctum)
– /database → migrations, factories, seeders
– /resources → Vue components, JS entrypoint, SASS, Blade views, localization
– /routes → API (routes/api.php), web (routes/web.php), console, channels
- **Patterns**: MVC on the backend, RESTful API endpoints, SPA frontend routing via Vue-Router, asset pipeline via webpack-mix.

##### Extract README insights
- Tech stack: Laravel 7.22.4, Vue.js 2.6.11, Bootstrap 4.5.2, LottiePlayer 0.5.1
- Purpose: modern client for an ancient Tamil text, search, audio playback, user auth.

##### Main components and interactions
a. **Client (Browser SPA)**
– Vue.js application (resources/js + compiled public/js/app.js)
– Vue-Router for navigation (Home, Section, Chapter, Kural pages, Login/Register)
– LottiePlayer + Bootstrap UI components
– Requests JSON via Axios to backend API
– Streams audio files from public/assets/audio
b. **Web Server / Reverse Proxy**
– Apache/Nginx serves public/index.php, static assets
– Forwards API calls (/api/*) to PHP runtime
c. **Laravel Backend**
– **HTTP Kernel & Middleware** (auth, CSRF, CORS, maintenance)
– **Controllers** (ChapterController, KuralController, Auth controllers, etc.)
– **Resources** (ChapterResource, KuralResource) transform Eloquent models to JSON
– **Models** & **Eloquent ORM** (Chapter, Section, Kural, ChapterGroup, User)
– **Services**: Auth (Sanctum or session), caching, queuing (if used), mailing, broadcasting (configurable)
d. **Database**
– MySQL/PostgreSQL (config/database.php) with users, chapters, sections, kurals tables
– Seeders & factories for test data
e. **Storage**
– Local filesystem for uploaded files (if any), logs, cache, sessions (config/storage)
f. **Build Toolchain**
– Node.js + webpack-mix (webpack.mix.js) compiles Vue, CSS/SASS into public/js & public/css

##### Architectural patterns / design principles
- **MVC** on backend, **RESTful** API for data, **SPA** on frontend
- Separation of concerns: Controllers + Resources (API layer), Models (data), Views (Blade only serves bootstrapping SPA)
- Asset pipeline isolation: Node/webpack compile before deployment
- Middleware chain ensures security, CORS, auth, etc.

##### Final checklist
– Notes on key frameworks (Laravel, Vue, Eloquent, webpack-mix)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Browser["Vue.js SPA"]:::client
        Blade["SPA Bootstrapping (Blade)"]:::client
        Router["Vue-Router"]:::client
        Components["Vue Components"]:::client
        Assets["Static Assets (Audio & Lottie)"]:::data
    end

    %% Build Tools
    subgraph "Build & Asset Pipeline"
        direction TB
        Build["Webpack-Mix"]:::tool
    end

    %% Application Layer
    subgraph "Web Server / PHP-FPM"
        direction TB
        WebServer["Web Server (Apache/Nginx)"]:::backend
        Entry["Entry Point & Config"]:::backend
    end

    %% Domain Layer
    subgraph "Laravel Backend"
        direction TB
        Kernel["HTTP Kernel & Middleware"]:::backend
        RoutesAPI["API Routes"]:::backend
        RoutesWeb["Web Routes"]:::backend
        Controllers["Controllers"]:::backend
        Resources["API Resources"]:::backend
        Models["Eloquent Models"]:::backend
        Providers["Service Providers"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Database["MySQL/PostgreSQL"]:::data
        Migrations["Migrations"]:::data
        Factories["Factories"]:::data
        Seeders["Seeders"]:::data
        ConfigDB["Database Config"]:::data
        StorageFS["File Storage"]:::data
        ConfigFS["Filesystem Config"]:::data
        AuthConfig["Auth & Session Config"]:::data
        CorsConfig["CORS & Security Config"]:::data
    end

    %% Connections
    Browser -->|"GET /"| WebServer
    Blade --> WebServer
    Browser -->|"AJAX /api/*"| RoutesAPI
    Browser -->|"Static GET"| Assets
    Build --> Browser
    Build --> Assets
    WebServer -->|"forward /api/*"| Kernel
    WebServer --> Entry
    Kernel --> RoutesAPI
    Kernel --> RoutesWeb
    RoutesAPI --> Controllers
    RoutesWeb --> Controllers
    Controllers --> Resources
    Controllers --> Models
    Models --> Database
    Controllers -->|"use Storage"| StorageFS
    ConfigDB --> Database
    Migrations --> Database
    Factories --> Database
    Seeders --> Database
    ConfigFS --> StorageFS
    AuthConfig --> Kernel
    CorsConfig --> Kernel

    %% Click Events
    click Browser "https://github.com/elan47/tirukkurals/blob/master/resources/js/app.js"
    click Router "https://github.com/elan47/tirukkurals/blob/master/resources/js/router.js"
    click Components "https://github.com/elan47/tirukkurals/tree/master/resources/js/components/pages/"
    click Blade "https://github.com/elan47/tirukkurals/blob/master/resources/views/welcome.blade.php"
    click Assets "https://github.com/elan47/tirukkurals/tree/master/public/assets/audio/"
    click Build "https://github.com/elan47/tirukkurals/blob/master/webpack.mix.js"
    click Entry "https://github.com/elan47/tirukkurals/blob/master/public/index.php"
    click Kernel "https://github.com/elan47/tirukkurals/blob/master/app/Http/Kernel.php"
    click RoutesAPI "https://github.com/elan47/tirukkurals/blob/master/routes/api.php"
    click RoutesWeb "https://github.com/elan47/tirukkurals/blob/master/routes/web.php"
    click Controllers "https://github.com/elan47/tirukkurals/tree/master/app/Http/Controllers/"
    click Resources "https://github.com/elan47/tirukkurals/tree/master/app/Http/Resources/"
    click Models "https://github.com/elan47/tirukkurals/tree/master/app/"
    click Providers "https://github.com/elan47/tirukkurals/blob/master/app/Providers/AppServiceProvider.php"
    click ConfigDB "https://github.com/elan47/tirukkurals/blob/master/config/database.php"
    click Migrations "https://github.com/elan47/tirukkurals/tree/master/database/migrations/"
    click Factories "https://github.com/elan47/tirukkurals/blob/master/database/factories/SectionFactory.php"
    click Seeders "https://github.com/elan47/tirukkurals/blob/master/database/seeds/SectionSeeder.php"
    click StorageFS "https://github.com/elan47/tirukkurals/tree/master/storage/"
    click ConfigFS "https://github.com/elan47/tirukkurals/blob/master/config/filesystems.php"
    click AuthConfig "https://github.com/elan47/tirukkurals/blob/master/config/auth.php"
    click CorsConfig "https://github.com/elan47/tirukkurals/blob/master/config/cors.php"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0288D1,color:#003c8f
    classDef backend fill:#E0F2E9,stroke:#43A047,color:#1b5e20
    classDef data fill:#FFF3E0,stroke:#FB8C00,color:#e65100
    classDef tool fill:#ECEFF1,stroke:#607D8B,color:#263238
```
