# cesium/safira architecture

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

- Interactive diagram: https://gitdiagram.com/cesium/safira
- Repository: https://github.com/cesium/safira

## Overview

##### Key Architectural Elements

a. Authentication & Authorization
- User Authentication (UserAuth)
- Role-based Access Control (Roles, Permissions)
- Staff Management

b. Feature Modules
- Badge System
- Store/Products
- Activities/Schedule
- Wheel Game
- Inventory Management

c. Supporting Services
- Mailer Service
- File Upload Service
- Telemetry

##### Interaction Flows

- User request flow through Router → LiveView/Controller → Context → Repo
- Authentication flow
- File upload paths
- Real-time features (LiveView connections)

##### Specific Implementation Details

Create subsections for:
- Frontend Architecture (assets/js, assets/css)
- Backend Services Organization
- Database Schema Relations (based on migrations)
- External Service Integrations

##### Important Notes

- Phoenix LiveView architecture as it's heavily used
- Separation between backoffice and regular app features
- Role-based permission system
- Event-driven nature of the system (indicated by presence of telemetry)

##### Additional Elements

- Component types
- Common patterns used

- The Phoenix/LiveView architecture
- The modular business logic organization
- The security and permission system
- The various features (badges, store, activities, etc.)
- Data flow and state management
- File upload and storage mechanisms

Remember to include notes about the real-time capabilities of the system through LiveView and any specific optimization patterns used in the application.

This will provide a comprehensive view of the system while maintaining clarity and usefulness for development and maintenance purposes.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Web_Layer
        Router["Router"]:::web
        Endpoint["Endpoint"]:::web
        LiveView["LiveView Components"]:::web
        Controllers["Controllers"]:::web
    end

    subgraph Core_Business_Logic
        Accounts["Accounts System"]:::core
        Activities["Activities Management"]:::core
        Companies["Companies Management"]:::core
        Contest["Contest System"]:::core
        Inventory["Inventory System"]:::core
        Store["Store System"]:::core
        Minigames["Minigames System"]:::core
    end

    subgraph Auth_Layer
        UserAuth["User Authentication"]:::auth
        Roles["Role Management"]:::auth
        Permissions["Permissions"]:::auth
    end

    subgraph Feature_Modules
        BadgeSystem["Badge System"]:::feature
        Products["Store/Products"]:::feature
        ActivitySystem["Activities"]:::feature
        WheelGame["Wheel Game"]:::feature
        InventoryItems["Inventory Items"]:::feature
    end

    subgraph Support_Services
        Mailer["Mailer Service"]:::support
        FileUpload["File Upload Service"]:::support
        Telemetry["Telemetry"]:::support
    end

    subgraph Data_Layer
        DB[(Database)]:::data
        Repo["Repository"]:::data
        Schema["Schema"]:::data
        Migrations["Migrations"]:::data
    end

    subgraph Frontend_Assets
        JS["JavaScript"]:::frontend
        CSS["CSS"]:::frontend
        UIComponents["UI Components"]:::frontend
    end

    %% Main Flow
    Router --> LiveView
    Router --> Controllers
    LiveView --> Core_Business_Logic
    Controllers --> Core_Business_Logic
    Core_Business_Logic --> Repo
    Repo --> DB

    %% Auth Flow
    Router --> UserAuth
    UserAuth --> Roles
    Roles --> Permissions

    %% Feature Connections
    Core_Business_Logic --> Feature_Modules
    Feature_Modules --> Repo
    
    %% Support Service Connections
    Core_Business_Logic --> Support_Services
    Feature_Modules --> Support_Services

    %% Frontend Connections
    LiveView --> Frontend_Assets

    %% Styling
    classDef web fill:#3498db
    classDef core fill:#2ecc71
    classDef auth fill:#e74c3c
    classDef feature fill:#f1c40f
    classDef support fill:#9b59b6
    classDef data fill:#f39c12
    classDef frontend fill:#1abc9c

    %% Click Events
    click Router "https://github.com/cesium/safira/blob/main/lib/safira_web/router.ex"
    click Endpoint "https://github.com/cesium/safira/blob/main/lib/safira_web/endpoint.ex"
    click LiveView "https://github.com/cesium/safira/tree/main/lib/safira_web/live/"
    click Controllers "https://github.com/cesium/safira/tree/main/lib/safira_web/controllers/"
    click Accounts "https://github.com/cesium/safira/tree/main/lib/safira/accounts/"
    click Activities "https://github.com/cesium/safira/tree/main/lib/safira/activities/"
    click Companies "https://github.com/cesium/safira/tree/main/lib/safira/companies/"
    click Contest "https://github.com/cesium/safira/tree/main/lib/safira/contest/"
    click Inventory "https://github.com/cesium/safira/tree/main/lib/safira/inventory/"
    click Store "https://github.com/cesium/safira/tree/main/lib/safira/store/"
    click Minigames "https://github.com/cesium/safira/tree/main/lib/safira/minigames/"
    click UserAuth "https://github.com/cesium/safira/blob/main/lib/safira_web/user_auth.ex"
    click Roles "https://github.com/cesium/safira/tree/main/lib/safira/accounts/roles/"
    click Permissions "https://github.com/cesium/safira/blob/main/lib/safira/accounts/roles/permissions.ex"
    click BadgeSystem "https://github.com/cesium/safira/blob/main/lib/safira/contest/badge.ex"
    click Products "https://github.com/cesium/safira/blob/main/lib/safira/store/product.ex"
    click ActivitySystem "https://github.com/cesium/safira/blob/main/lib/safira/activities/activity.ex"
    click WheelGame "https://github.com/cesium/safira/blob/main/lib/safira/minigames/wheel_drop.ex"
    click InventoryItems "https://github.com/cesium/safira/blob/main/lib/safira/inventory/item.ex"
    click Mailer "https://github.com/cesium/safira/blob/main/lib/safira/mailer.ex"
    click FileUpload "https://github.com/cesium/safira/tree/main/lib/safira/uploaders/"
    click Telemetry "https://github.com/cesium/safira/blob/main/lib/safira_web/telemetry.ex"
    click Repo "https://github.com/cesium/safira/blob/main/lib/safira/repo.ex"
    click Schema "https://github.com/cesium/safira/blob/main/lib/safira/schema.ex"
    click Migrations "https://github.com/cesium/safira/tree/main/priv/repo/migrations/"
    click JS "https://github.com/cesium/safira/tree/main/assets/js/"
    click CSS "https://github.com/cesium/safira/tree/main/assets/css/"
    click UIComponents "https://github.com/cesium/safira/tree/main/assets/css/components/"
```
