# ksjaay/lunalytics architecture

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

- Interactive diagram: https://gitdiagram.com/ksjaay/lunalytics
- Repository: https://github.com/ksjaay/lunalytics

## Overview

- Frontend (Client/UI):
- Represented by the “app” folder. This contains React components (organized by pages, modals, navigation, UI elements, etc.), context hooks (e.g., in app/context) for global state, and styling (SCSS files).
- Key areas include pages (login, register, monitor, notifications, status, setup), different UI elements (status bars, tables, dropdowns), and component libraries (accordion, buttons, modals, etc.).
- Backend (API/Server):
- Found in the “server” folder, built with Node.js. This includes the API endpoints (routes folder), middleware for authentication, authorization, and various business functions (monitor management, user accounts, notifications, status pages).
- Several sub-components here: Routes, Middleware (authentication, monitor, status, user, etc.), utility functions (in server/utils), and server initialization (server/index.js).
- Database Access Layer:
- Located under “server/database” and “server/database/sqlite”. This encapsulates SQL queries, database setup scripts, and migration scripts (found in the “scripts/migrations” folder). It supports multiple database types (SQLite primarily noted, with PostgreSQL support also mentioned in the roadmap).
- Notification/Integration Services:
- Both “server/notifications” and “shared/notifications” provide integrations with external notification services like Discord, Slack, Telegram, and Webhooks.
- Shared and Utility Modules:
- The “shared” folder contains common constants, schemas, permissions, validators, and utilities used across frontend and backend to keep data definitions and helper functionality consistent.
- Testing and CI/CD:
- Test directories (test/e2e, test/server) cover end-to-end and unit tests.
- CI/CD-related configuration exists in .github/workflows, along with Docker (Dockerfile) and other configuration files. This ensures code quality and facilitates self-hosted deployment.

##### Relationships and Interactions
- Data Flow:
- The Frontend (React UI) makes API calls to the Backend Server.
- The Backend processes requests through middleware and route handlers, interacts with the Database (via predefined queries), and sends notifications through integration modules.
- Helper utilities and shared modules are used across both client and server layers.
- Service Dependencies:
- The server handles authentication, monitor creation/editing, notifications management, and status page configuration.
- The database layer stores user data, monitoring configurations, historical uptime logs, etc.
- Notification services receive alerts triggered by server logic.
- CI/CD pipelines and Docker support deployment and testing, ensuring that these interactions run smoothly.

##### Architectural Patterns & Design Principles
- Modularity & Separation of Concerns:
- Clear separation between frontend (React components and UI contexts) and backend (API endpoints, middleware, and database queries).
- Micro-structure within the frontend with component-based reactive design.
- Backend structured with clear routing, middleware layering, and business logic modules.
- Shared Core:
- Use of “shared” modules to maintain consistent data formats, constants, and validators between client and server.
- Extensibility:
- Notification integrations and status page customization allow for additional external services and new UI components as the project grows.
- Testing & Continuous Integration:
- Separate test directories and GitHub workflow files, emphasizing robust testing coverage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Client Layer)"
        FE["React Application (app/)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (API Layer)"
        BE["Node.js Server (server/)"]:::backend
        ROUTE["API Routes (server/routes)"]:::backend
        MIDDLE["Middleware (server/middleware)"]:::backend
        UTIL["Utilities (server/utils)"]:::backend
        INIT["Server Initialization (server/index.js)"]:::backend
    end

    %% Database Layer
    subgraph "Data Persistence Layer"
        DB["Database Layer (server/database/)"]:::database
        DBS["SQLite Module (server/database/sqlite)"]:::database
        MIG["Migration Scripts (scripts/migrations)"]:::database
    end

    %% External Notification Services
    subgraph "External Services"
        NOTIF["Notification Modules (server/notifications/)"]:::notification
        NOTIF_SHARED["Notification Modules (shared/notifications/)"]:::notification
    end

    %% Shared Modules
    subgraph "Shared Modules"
        SHARED["Shared & Utility Modules (shared/)"]:::shared
    end

    %% Testing & CI/CD
    subgraph "Testing & CI/CD"
        TEST["Test Suites (test/)"]:::test
        CICD["CI/CD Configs (.github/workflows/)"]:::test
        DOCKER["Docker Configuration (Dockerfile)"]:::test
    end

    %% Data Flow Connections
    FE -->|"HTTP/API_calls"| BE
    BE -->|"Calls_Routes"| ROUTE
    BE -->|"Uses_Middleware"| MIDDLE
    BE -->|"Executes_Utilities"| UTIL
    BE -->|"Initializes_via"| INIT
    BE -->|"Queries"| DB
    BE -->|"Manages_SQL"| DBS
    DBS -->|"Includes_Migrations"| MIG
    BE -->|"Triggers_Notifications"| NOTIF
    BE -->|"Integrates_with"| NOTIF_SHARED
    BE -->|"Utilizes"| SHARED
    FE -->|"Accesses_Shared"| SHARED

    %% Testing and CI/CD interactions
    FE -->|"Tested_By"| TEST
    BE -->|"Tested_By"| TEST
    CICD -->|"Executes"| TEST
    CICD -->|"Builds_with"| DOCKER

    %% Click Events
    click FE "https://github.com/ksjaay/lunalytics/tree/main/app/"
    click BE "https://github.com/ksjaay/lunalytics/tree/main/server/"
    click ROUTE "https://github.com/ksjaay/lunalytics/tree/main/server/routes"
    click MIDDLE "https://github.com/ksjaay/lunalytics/tree/main/server/middleware"
    click UTIL "https://github.com/ksjaay/lunalytics/tree/main/server/utils"
    click INIT "https://github.com/ksjaay/lunalytics/blob/main/server/index.js"
    click DB "https://github.com/ksjaay/lunalytics/tree/main/server/database/"
    click DBS "https://github.com/ksjaay/lunalytics/tree/main/server/database/sqlite"
    click MIG "https://github.com/ksjaay/lunalytics/tree/main/scripts/migrations"
    click NOTIF "https://github.com/ksjaay/lunalytics/tree/main/server/notifications/"
    click NOTIF_SHARED "https://github.com/ksjaay/lunalytics/tree/main/shared/notifications/"
    click SHARED "https://github.com/ksjaay/lunalytics/tree/main/shared/"
    click TEST "https://github.com/ksjaay/lunalytics/tree/main/test/"
    click CICD "https://github.com/ksjaay/lunalytics/tree/main/.github/workflows/"
    click DOCKER "https://github.com/ksjaay/lunalytics/tree/main/Dockerfile"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef database fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef notification fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef shared fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef test fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
```
