# ascoor/almadar architecture

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

- Interactive diagram: https://gitdiagram.com/ascoor/almadar
- Repository: https://github.com/ascoor/almadar

## Overview

##### Project type and purpose
- This is a full-stack web application (“Almadar”) for legal and administrative management.
- Backend: Laravel 10 (PHP 8.2) providing RESTful APIs, business logic, authentication/authorization, events & notifications, PDF/text processing, database migrations/seeders.
- Frontend: React 18 + Vite + Tailwind CSS + PWA for a responsive single-page UI (dashboard, user management, litigations, contracts, investigations, legal advices, reports, settings, archive, profile).

##### File structure
- Top-level:
- backend/ – Laravel app (MVC in app/, config, routes/, database/, resources/, public/).
- frontend/ – React app (public/, src/ with components/pages/services/hooks/context).
- start.sh – local startup script.
- Backend folders:
- app/Models, Controllers, Events, Notifications, Providers.
- routes/api.php & web.php.
- config/ includes CORS, auth, queue, sanctum, spatie/permission.
- database/ migrations & seeders.
- public/index.php as entry point.
- Frontend folders:
- src/components – feature-organized UI components (Contracts, Investigations, LegalAdvices, Litigations, Notifications, Settings, Users, auth, common, dashboard, ui).
- src/pages – route-level page components.
- src/services/api – axios-based wrappers for backend endpoints.
- src/context & hooks – React Context and custom hooks for state, Pusher/Echo integration.
- public/ assets and manifest for PWA.

##### README for additional insights
- Confirms high-level modules (dashboard, user management, litigations, contracts, investigations, legal project management, legal advices, reports, settings, archive, profile).
- Lists key libraries: Laravel Sanctum, Spatie/permission, phpword, pdf-to-text, React Router, react-pdf, tesseract.js, pusher-js, sonner.
- Emphasizes responsive layout, notification system, PDF viewer.

##### Elements
- Components labeled: React SPA, Laravel API, Database, Cache/Queue, File Storage, External Services
- HTTP requests/responses
- Event broadcasting/receiving
- Read/write to database/storage/queue
- Frontend (blue rectangles)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (React SPA)" 
        direction TB
        Browser["User Browser"]:::external
        SPA["React SPA"]:::frontend
        Entry["Entry Point\n(main.jsx)"]:::frontend
        Pages["Route-level Pages"]:::frontend
        Components["Shared Components"]:::frontend
        Services["Service Layer\n(API wrappers)"]:::frontend
        Context["Context & Hooks"]:::frontend
        EchoInit["Echo Initializer\n(Pusher + Echo)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Laravel API Server)"
        direction TB
        RoutesAPI["API Routes\n(api.php)"]:::backend
        RoutesWeb["Web Routes\n(web.php)"]:::backend
        Controllers["Controllers"]:::backend
        Models["Models"]:::backend
        Events["Events"]:::backend
        Notifications["Notifications"]:::backend
        Providers["Providers"]:::backend
        Middleware["Middleware"]:::backend
        ConsoleKernel["Console Kernel\n(Jobs & Workers)"]:::backend
        Configs["Configuration\n(auth, cors, sanctum, queue, permission, broadcasting, filesystems, gpdf)"]:::backend
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        direction TB
        DB[(Database)]:::datastore
        Cache[(Cache / Queue)]:::datastore
        Storage[(File Storage)]:::datastore
        Pusher["Pusher Service"]:::external
        OCR["Tesseract.js (Client OCR)"]:::external
        DocProc["phpword / pdf-to-text"]:::external
    end

    %% Startup Script
    Start["Local Startup\n(start.sh)"]:::service

    %% Connections
    Browser -->|"loads SPA"| SPA
    SPA -->|"calls API"| RoutesAPI
    SPA -->|"listens events"| EchoInit
    SPA --> Services
    SPA --> Pages
    SPA --> Components
    SPA --> Context
    SPA --> Entry

    RoutesAPI -->|"dispatch to"| Controllers
    RoutesWeb --> Controllers
    Controllers -->|"read/write"| Models
    Controllers -->|"fire events"| Events
    Controllers -->|"send notifications"| Notifications
    Controllers -->|"authorize"| Providers
    Controllers -->|"apply middleware"| Middleware
    Controllers -->|"dispatch jobs"| ConsoleKernel
    Controllers -->|"read/write"| DB
    Controllers -->|"read/write"| Cache
    Controllers -->|"store files"| Storage

    ConsoleKernel -->|"process jobs"| Cache
    ConsoleKernel --> Controllers

    Events -->|"broadcast"| Pusher
    EchoInit -->|"subscribe"| Pusher
    OCR -.-> SPA
    DocProc -.-> Controllers

    Start --> SPA
    Start --> RoutesAPI

    %% Click Events
    click SPA "https://github.com/ascoor/almadar/tree/master/frontend/src"
    click Entry "https://github.com/ascoor/almadar/blob/master/frontend/src/main.jsx"
    click Pages "https://github.com/ascoor/almadar/tree/master/frontend/src/pages"
    click Components "https://github.com/ascoor/almadar/tree/master/frontend/src/components"
    click Services "https://github.com/ascoor/almadar/tree/master/frontend/src/services/api"
    click Context "https://github.com/ascoor/almadar/tree/master/frontend/src/context"
    click EchoInit "https://github.com/ascoor/almadar/blob/master/frontend/src/components/EchoInitializer.jsx"

    click Controllers "https://github.com/ascoor/almadar/tree/master/backend/app/Http/Controllers"
    click Models "https://github.com/ascoor/almadar/tree/master/backend/app/Models"
    click Events "https://github.com/ascoor/almadar/tree/master/backend/app/Events"
    click Notifications "https://github.com/ascoor/almadar/tree/master/backend/app/Notifications"
    click Providers "https://github.com/ascoor/almadar/tree/master/backend/app/Providers"
    click Middleware "https://github.com/ascoor/almadar/tree/master/backend/app/Http/Middleware"
    click RoutesAPI "https://github.com/ascoor/almadar/blob/master/backend/routes/api.php"
    click RoutesWeb "https://github.com/ascoor/almadar/blob/master/backend/routes/web.php"
    click ConsoleKernel "https://github.com/ascoor/almadar/blob/master/backend/app/Console/Kernel.php"
    click Configs "https://github.com/ascoor/almadar/tree/master/backend/config"
    click DB "https://github.com/ascoor/almadar/tree/master/backend/database/migrations"
    click DB "https://github.com/ascoor/almadar/tree/master/backend/database/seeders"
    click Cache "https://github.com/ascoor/almadar/blob/master/backend/config/queue.php"
    click Storage "https://github.com/ascoor/almadar/tree/master/backend/storage/app/public"
    click Pusher "https://github.com/ascoor/almadar/blob/master/backend/config/broadcasting.php"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#004D40;
    classDef backend fill:#E8F5E9,stroke:#1B5E20,color:#2E7D32;
    classDef datastore fill:#FFF3E0,stroke:#EF6C00,color:#E65100;
    classDef external fill:#F3E5F5,stroke:#6A1B9A,color:#4A148C;
    classDef service fill:#ECEFF1,stroke:#455A64,color:#263238;
```
