# welllucky/services architecture

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

- Interactive diagram: https://gitdiagram.com/welllucky/services
- Repository: https://github.com/welllucky/services

## Overview

##### Project type and purpose
- This is a full-stack, service-desk/helpdesk web application called “Services,” built with Next.js 14 (React) on the front end and Node/TypeORM/MySQL behind the scenes via Next API Handlers.
- It streamlines ticket creation in three steps (describe issue, add evidence, confirm) and hides complexity (automatically assigns sector, priority, etc.).

##### File structure
- Frontend (UI & routing) lives under src/app (Next.js App Router), src/screens, src/components, src/assets, src/styles, and Storybook docs under .storybook & src/docs.
- Backend API logic is in Next API Routes (src/app/api/...) and a separate src/server folder containing controllers, functions (auth, config, protectController, etc.), and the server entrypoint.
- Shared abstractions & implementations:
- “implementations/client” & “implementations/server” for DI layers (Analytics, HttpClient, JWT, Crypto, FeatureFlag, Firebase, Messaging).
- src/utils/providers and src/utils/stores for React context/Zustand state management.
- Types & DTOs under src/types.
- Config and environment files: next.config.js, .env, sentry configs, deepsource, ESLint, Prettier, CI workflows, Playwright tests, and Vercel deployment (vercel.json).

##### Main components
a. Frontend (Next.js App)
- Pages & Layout (src/app)
- UI Components & Screens (src/components, src/screens)
- Resource Providers & State Stores (src/utils/providers, src/utils/stores)
- Client Abstractions & Infra (Analytics, HttpClient, FeatureFlag, Messaging, Firebase)
b. Backend/API (Next API Routes + custom server logic)
- Route Handlers (src/app/api/…)
- Controller Layer (src/server/controllers)
- Business Functions (src/server/functions: auth, getEnv, protect, revalidate)
- Infrastructure Abstractions (Crypto, JWT, Http) & Agents (implementations/server/infra)
c. Persistence Layer
- TypeORM Entities & MySQL Database (configured via env vars)
d. External Services
- Sentry (Error monitoring)
- Firebase (Push messaging / Remote config / Feature flags)
- Analytics (e.g., Google Analytics or custom via abstractions)
e. CI/CD & Testing
- Playwright E2E & Jest/RTL unit tests
- GitHub Actions workflows and Deepsource scanning
- Storybook documentation

##### Relationships & data flow
- User interacts with Frontend UI (React)
- UI calls HttpClient to send REST requests to Next.js API Routes
- API route maps to Controller → calls business functions → uses infra agents (Crypto/JWT) → accesses MySQL via TypeORM
- Controllers return JSON to UI; UI updates state via Providers/Zustand
- Frontend sends telemetry to Analytics and error logs to Sentry asynchronously
- Push notifications via Firebase Messaging SW

##### Architectural patterns & design principles
- Layered architecture: Presentation (pages/screens), Service (controllers/functions), Data (ORM/DB)
- Dependency inversion via Abstractions/Implementations (IoC pattern)
- Provider pattern in React for cross-cutting concerns (Auth, Feature Flags, Services)
- Next.js App Router for file-based routing and SSR/SSG
- Separation of concerns: UI vs. business logic vs. infrastructure

##### Detail level & essential elements
- Don’t over-aggregate: Show meaningful subcomponents (e.g., HttpClient vs. FeatureFlag infra)
- DI/Provider boundaries to illustrate how abstractions map to concrete implementations
- Next.js file-based router as the entry point for both pages and API endpoints
- Environment variables/configuration layer (DB, Sentry, Firebase) is visible

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Next.js App)" 
        direction TB
        AppPages["Pages & Layout"]:::frontend
        UIComponents["UI Components"]:::frontend
        Screens["Screens"]:::frontend
        Providers["Resource Providers"]:::frontend
        Stores["State Stores"]:::frontend
        ClientInfra["Client Abstractions & Infra"]:::infra
    end

    %% API Layer
    subgraph "Next.js API Layer"
        direction TB
        APIRoutes["API Routes"]:::api
    end

    %% Server Layer
    subgraph "Server (Controllers & Functions)"
        direction TB
        Controllers["Controller Layer"]:::api
        Functions["Business Functions"]:::api
        ServerInfra["Server Abstractions & Agents"]:::infra
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Database["MySQL (TypeORM)"]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Sentry["Sentry Error Monitoring"]:::external
        Firebase["Firebase (Messaging/FeatureFlags)"]:::external
        Analytics["Analytics"]:::external
    end

    %% CI/CD & Testing
    subgraph "CI/CD & Testing"
        direction TB
        CI["CI/CD Workflows"]:::external
        Storybook["Storybook Documentation"]:::external
        Docs["Docs"]:::external
        E2E["E2E & Playwright Tests"]:::external
    end

    %% Connections
    AppPages -->|uses| UIComponents
    UIComponents --> Screens
    Screens --> Providers
    Providers --> Stores
    Screens -->|calls| ClientInfra
    ClientInfra -->|HTTP Request| APIRoutes
    APIRoutes -->|invokes| Controllers
    Controllers -->|calls| Functions
    Functions -->|uses| ServerInfra
    ServerInfra -->|queries| Database
    Database -->|responds| Functions
    Functions -->|returns data| Controllers
    Controllers -->|JSON Response| APIRoutes
    APIRoutes -->|HTTP Response| ClientInfra
    ClientInfra -->|updates| Stores
    Screens -->|reads state| Stores

    %% Telemetry & Notifications
    Screens -->|logs errors| Sentry
    Screens -->|sends telemetry| Analytics
    Firebase -->|push notifications| Screens

    %% Config/Deployment Boundary
    subgraph "Config & Deployment"
        direction TB
        Env[".env, next.config.js"]:::external
        Vercel["Vercel Deployment"]:::external
    end
    Env --> APIRoutes
    Env --> ClientInfra
    Env --> ServerInfra
    Vercel --> AppPages
    Vercel --> APIRoutes

    %% Click Events
    click AppPages "https://github.com/welllucky/services/tree/main/src/app"
    click UIComponents "https://github.com/welllucky/services/tree/main/src/components"
    click Screens "https://github.com/welllucky/services/tree/main/src/screens"
    click Providers "https://github.com/welllucky/services/tree/main/src/utils/providers"
    click Stores "https://github.com/welllucky/services/tree/main/src/utils/stores"
    click ClientInfra "https://github.com/welllucky/services/tree/main/src/implementations/client"
    click APIRoutes "https://github.com/welllucky/services/tree/main/src/app/api"
    click Controllers "https://github.com/welllucky/services/tree/main/src/server/controllers"
    click Functions "https://github.com/welllucky/services/tree/main/src/server/functions"
    click ServerInfra "https://github.com/welllucky/services/tree/main/src/implementations/server"
    click Sentry "https://github.com/welllucky/services/blob/main/sentry.client.config.ts"
    click CI "https://github.com/welllucky/services/tree/main/.github/workflows"
    click Storybook "https://github.com/welllucky/services/blob/main/.storybook"
    click Docs "https://github.com/welllucky/services/tree/main/src/docs"
    click E2E "https://github.com/welllucky/services/tree/main/tests/e2e"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6,stroke-width:1px;
    classDef api fill:#E6F4EA,stroke:#057a55,color:#057a55,stroke-width:1px;
    classDef infra fill:#FFF4E5,stroke:#d9822b,color:#d9822b,stroke-width:1px;
    classDef db fill:#F0F0F0,stroke:#6A737D,color:#6A737D,stroke-width:1px;
    classDef external fill:#F5E6FF,stroke:#6f42c1,color:#6f42c1,stroke-width:1px;
```
