# gaspardculis/regionoix architecture

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

- Interactive diagram: https://gitdiagram.com/gaspardculis/regionoix
- Repository: https://github.com/gaspardculis/regionoix

## Overview

##### Project type and purpose
- This is a full-stack e-commerce/web-app called “Regionoix.”
- Frontend: Angular single-page application (in src/app), generated OpenAPI client for all backend APIs.
- Backend: Rust REST API (backend/src) with SeaORM entities, DTOs, routes and services.
- Persistence: PostgreSQL (backend/sql), Redis, MeiliSearch, S3, Stripe integration.
- Deployment: NixOS/Caddy for reverse-proxy, GitHub Actions for CI.

##### Top-level components
A. Frontend SPA (Angular)
- UI pages, components, state & service layers
- Generated OpenAPI client module
B. Backend API Service (Rust)
- HTTP server (main.rs → routes)
- Domain layers: entities, DTOs, services (database, search, storage, payments)
- Tools: search indexer CLI
C. Data Stores & External Services
- PostgreSQL (SQL scripts)
- Redis (session/cache)
- MeiliSearch (full-text search index)
- S3 (object storage for uploads)
- Stripe (payment processing)
D. Infrastructure & Deployment
- Caddy reverse proxy
- NixOS modules for each service
- GitHub Actions workflows

##### Relationships & data flows
- Frontend ↔ Backend over HTTPS
- Auth (login/register/status/logout)
- Product/catalog queries, basket operations, orders, payments
- Backend → PostgreSQL for CRUD
- Backend → Redis for caching/rate-limiting/session
- Backend → MeiliSearch for indexing/search
- Backend → S3 for file upload/download
- Backend → Stripe for payment sessions/webhooks
- search_indexer tool → PostgreSQL → MeiliSearch (batch re-index)
- Caddy proxy → routes requests to Angular static assets or Rust API

##### Architectural patterns & design principles
- Layered “Clean” architecture:
- Routes (controllers) → Services (business logic) → Entities + DTOs → Data layer
- API-first: OpenAPI spec (src/swaggers/regionoix.json) → client generation
- Configuration as code: NixOS modules per service
- Clear separation: frontend vs backend vs infrastructure
- Use of domain objects (DTOs/entities) for strict typing and validation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Tier
    subgraph "Client Tier"
        direction TB
        FrontendSPA["Angular SPA"]:::frontend
        AngularPages["UI Pages & Components"]:::frontend
        AngularServices["State & Services"]:::frontend
        GeneratedClient["OpenAPI Client Module"]:::frontend
    end

    %% Server Tier
    subgraph "Server Tier"
        direction TB
        BackendMain["Rust API Service<br/>(main.rs)"]:::backend
        RustRoutes["Route Handlers<br/>(backend/src/routes)"]:::backend
        BusinessServices["Business Logic Services"]:::backend
        Entities["Domain Entities<br/>(SeaORM)"]:::backend
        DTOs["Data Transfer Objects"]:::backend
        StripeService["Stripe Integration Service"]:::backend
        SearchIndexer["Search Indexer CLI"]:::tools
    end

    %% Datastores
    subgraph "Datastores & External" 
        direction TB
        Postgres["PostgreSQL"]:::datastore
        Redis["Redis"]:::datastore
        MeiliSearch["MeiliSearch"]:::datastore
        S3["S3 Object Storage"]:::external
        StripeAPI["Stripe API"]:::external
    end

    %% Infrastructure & CI
    subgraph "Infrastructure & CI"
        direction TB
        Caddy["Caddy Reverse Proxy"]:::infra
        NixModules["NixOS Modules"]:::infra
        CI["GitHub Actions CI"]:::infra
    end

    %% Client to Server
    FrontendSPA -->|HTTPS/REST| BackendMain
    GeneratedClient -->|Uses OpenAPI| BackendMain

    %% Frontend internal
    FrontendSPA --> AngularPages
    FrontendSPA --> AngularServices
    AngularServices --> GeneratedClient

    %% Server internals
    BackendMain --> RustRoutes
    RustRoutes --> BusinessServices
    BusinessServices --> Entities
    BusinessServices --> DTOs
    BusinessServices --> StripeService
    BusinessServices --> SearchIndexer

    %% Data flows
    BusinessServices -->|SQL Queries| Postgres
    BusinessServices -->|Cache GET/SET| Redis
    BusinessServices -->|Index/Write| MeiliSearch
    BusinessServices -->|File Upload/Download| S3
    StripeService -->|Payment API Calls| StripeAPI

    SearchIndexer -->|Batch Re-index| Postgres
    SearchIndexer -->|Batch Re-index| MeiliSearch

    %% Infra flows
    Caddy -->|Serves SPA| FrontendSPA
    Caddy -->|Proxies API| BackendMain
    NixModules --> Caddy
    NixModules --> BackendMain
    NixModules --> FrontendSPA
    CI --> BackendMain
    CI --> FrontendSPA
    CI --> NixModules

    %% Click Events
    click FrontendSPA "https://github.com/gaspardculis/regionoix/tree/main/src/app"
    click GeneratedClient "https://github.com/gaspardculis/regionoix/tree/main/src/app/generated/clients/regionoix-client"
    click AngularPages "https://github.com/gaspardculis/regionoix/tree/main/src/app/pages"
    click AngularServices "https://github.com/gaspardculis/regionoix/tree/main/src/app/services"
    click BackendMain "https://github.com/gaspardculis/regionoix/blob/main/backend/src/main.rs"
    click RustRoutes "https://github.com/gaspardculis/regionoix/tree/main/backend/src/routes"
    click Entities "https://github.com/gaspardculis/regionoix/tree/main/backend/src/entities"
    click DTOs "https://github.com/gaspardculis/regionoix/tree/main/backend/src/dtos"
    click BusinessServices "https://github.com/gaspardculis/regionoix/tree/main/backend/src/services"
    click SearchIndexer "https://github.com/gaspardculis/regionoix/blob/main/backend/src/tools/search_indexer/main.rs"
    click PostgresSchema "https://github.com/gaspardculis/regionoix/tree/main/backend/sql"
    click Redis "https://github.com/gaspardculis/regionoix/blob/main/nix/Raviole1/services/redis.nix"
    click MeiliSearch "https://github.com/gaspardculis/regionoix/blob/main/nix/Raviole1/services/meilisearch.nix"
    click S3 "https://github.com/gaspardculis/regionoix/blob/main/nix/Raviole1/services/default.nix"
    click StripeService "https://github.com/gaspardculis/regionoix/blob/main/backend/src/services/stripe.rs"
    click Caddy "https://github.com/gaspardculis/regionoix/blob/main/nix/Raviole1/services/caddy.nix"
    click BackendNix "https://github.com/gaspardculis/regionoix/blob/main/nix/pkgs/regionoix-backend/default.nix"
    click FrontendNix "https://github.com/gaspardculis/regionoix/blob/main/nix/pkgs/regionoix-frontend/default.nix"
    click NixModules "https://github.com/gaspardculis/regionoix/blob/main/nix/Raviole1/services/backend.nix"
    click NixModules "https://github.com/gaspardculis/regionoix/blob/main/nix/Raviole1/services/web.nix"
    click OpenAPISpec "https://github.com/gaspardculis/regionoix/blob/main/src/swaggers/regionoix.json"
    click CI "https://github.com/gaspardculis/regionoix/blob/main/ .github/workflows/check-backend.yaml"
    click CI "https://github.com/gaspardculis/regionoix/blob/main/ .github/workflows/check-frontend.yaml"
    click CI "https://github.com/gaspardculis/regionoix/blob/main/ .github/workflows/check-nix.yaml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0066CC,color:#003366;
    classDef backend fill:#DFF2D8,stroke:#339933,color:#005500;
    classDef datastore fill:#FFF7CC,stroke:#CC9900,color:#665500;
    classDef external fill:#FFE5D0,stroke:#FF6600,color:#993300;
    classDef tools fill:#E0E0E0,stroke:#999999,color:#333333;
    classDef infra fill:#F0F0FF,stroke:#6666CC,color:#333366;
```
