# yasblha/projet-facturation architecture

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

- Interactive diagram: https://gitdiagram.com/yasblha/projet-facturation
- Repository: https://github.com/yasblha/projet-facturation

## Overview

##### Project Type and Purpose
- AquaERP is a full-stack, Kubernetes-deployed microservices platform for water-sector contract, billing, and field-operation management.
- Frontend: Vue.js 3 + TypeScript + Pinia.
- Backend: A suite of NestJS microservices behind an API Gateway, communicating via REST and RabbitMQ.
- Shared infrastructure: PostgreSQL, RabbitMQ, Traefik ingress, Prometheus/Grafana monitoring.

##### File Structure Highlights
- Top-level “frontend” folder: Vue SPA, static assets, Dockerfile.
- “services/…-service” folders: each a self-contained NestJS microservice (auth, contrat, operation, facture, mailer, intervention, workflow, api-gateway).
- “Database” folder: central Sequelize config, migrations, models.
- “k8s” + “infrastructure” folders: Kubernetes manifests, ingress, monitoring, config, adapters.
- “scripts”: deployment helpers, manifest generators, DB helpers.

##### Key Architectural Patterns
- API Gateway pattern for a single entry point.
- Microservices with CQRS-style structure (DTOs, use-cases, repositories).
- Event-driven communication via RabbitMQ for async workflows.
- Shared or per-service PostgreSQL persistence.
- Deployed on Kubernetes with Traefik ingress, HPA, NetworkPolicies, and observability stack.

##### Main Components
a) User Browser & Mobile (Clients)
– Connects via HTTPS to the Frontend.
b) Frontend (Vue.js SPA)
– Served behind Traefik ingress & CDN.
– Interacts with API Gateway over HTTPS/REST.
c) Traefik Ingress Controller (K8s)
– Routes external traffic to Frontend or API Gateway.
d) API Gateway (NestJS)
– Synchronous REST proxy for client requests.
– Asynchronous publisher to RabbitMQ for certain commands/events.
– Routes to individual microservices.
e) RabbitMQ Message Broker
– Central event bus for inter-service async communication.
– Exchanges for domain events (contractCreated, invoiceIssued, etc.).
f) Microservices
– Auth Service
– Contrat Service
– Operation Service
– Facture Service
– Intervention Service
– Mailer Service
– Workflow Service
Each:
- Exposes HTTP endpoints (including /health).
- Subscribes to RabbitMQ queues/exchanges.
- Reads/writes to PostgreSQL.
- Publishes events to RabbitMQ.
g) PostgreSQL Database
– Persistent volume claim.
– Single instance or per-service schemas.
h) Monitoring & Logging
– Prometheus scrapes /metrics endpoints.
– Grafana dashboards.
– Elasticsearch or external logger adapter (optional).
i) CI/CD & GitHub Actions
– selective-deploy workflows triggering Docker builds and k8s updates.

##### Relationships & Data Flows
- Frontend → (HTTPS/REST) → API Gateway
- API Gateway → (REST) → Microservice endpoints for sync operations
- API Gateway → (RabbitMQ) → Exchanges for async commands (e.g., sendInvitationEmail)
- Microservices → (REST) → Other services if required (rare)
- Microservices ↔ (RabbitMQ) ↔ Microservices for domain event propagation
- Each Microservice → (SQL) → PostgreSQL
- Prometheus ← (metrics endpoints) ← Each service + RabbitMQ + DB
- Grafana visualizes Prometheus data

##### Technologies & Frameworks
- Frontend: Vue 3, Pinia, Vite, Cypress (E2E).
- Backend: NestJS, TypeScript, Sequelize (or TypeORM), RabbitMQ.
- Deployment: Docker, Kubernetes (Traefik, HPA, NetworkPolicies), cert-manager.
- Monitoring: Prometheus, Grafana.
- CI/CD: GitHub Actions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Browser["User Browser"]:::ui
    Mobile["Mobile App"]:::ui

    %% Ingress & Frontend
    Traefik["Traefik Ingress Controller"]:::ui
    Frontend["Vue.js SPA"]:::ui
    click Frontend "https://github.com/yasblha/projet-facturation/tree/develop/frontend/"
    click Traefik "https://github.com/yasblha/projet-facturation/blob/develop/k8s/ingress.yaml"

    %% API Gateway
    ApiGateway["API Gateway (NestJS)"]:::gateway
    click ApiGateway "https://github.com/yasblha/projet-facturation/tree/develop/services/api-gateway/"

    %% Message Broker
    RabbitMQ["RabbitMQ Message Broker"]:::broker
    click RabbitMQ "https://github.com/yasblha/projet-facturation/blob/develop/k8s/services/rabbitmq.yaml"

    %% Microservices Group
    subgraph "Microservices (aquaerp)" 
        direction TB
        AuthSvc["Auth Service\n/health"]:::service
        click AuthSvc "https://github.com/yasblha/projet-facturation/tree/develop/services/auth-service/"
        ContratSvc["Contrat Service\n/health"]:::service
        click ContratSvc "https://github.com/yasblha/projet-facturation/tree/develop/services/contrat-service/"
        OperationSvc["Operation Service\n/health"]:::service
        click OperationSvc "https://github.com/yasblha/projet-facturation/tree/develop/services/operation-service/"
        FactureSvc["Facture Service\n/health"]:::service
        click FactureSvc "https://github.com/yasblha/projet-facturation/tree/develop/services/facture-service/"
        InterventionSvc["Intervention Service\n/health"]:::service
        click InterventionSvc "https://github.com/yasblha/projet-facturation/tree/develop/services/intervention-service/"
        MailerSvc["Mailer Service\n/health"]:::service
        click MailerSvc "https://github.com/yasblha/projet-facturation/tree/develop/services/mailer-service/"
        WorkflowSvc["Workflow Service\n/health"]:::service
        click WorkflowSvc "https://github.com/yasblha/projet-facturation/tree/develop/services/workflow-service/"
    end

    %% Database
    Postgres["PostgreSQL Database"]:::db
    click Postgres "https://github.com/yasblha/projet-facturation/tree/develop/Database/"

    %% Monitoring & Logging
    subgraph "Monitoring (monitoring)"
        direction TB
        Prometheus["Prometheus"]:::monitor
        click Prometheus "https://github.com/yasblha/projet-facturation/blob/develop/k8s/monitoring/prometheus-*.yaml"
        Grafana["Grafana"]:::monitor
        click Grafana "https://github.com/yasblha/projet-facturation/blob/develop/k8s/monitoring/grafana-*.yaml"
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        GitHubActions["GitHub Actions"]:::cicd
        click GitHubActions "https://github.com/yasblha/projet-facturation/blob/develop/.github/workflows/deploy.yml"
        DockerRegistry["Docker Registry"]:::cicd
        Scripts["Deployment Scripts"]:::cicd
        click Scripts "https://github.com/yasblha/projet-facturation/tree/develop/scripts/"
    end

    %% Connections
    Browser -->|"HTTPS"| Traefik
    Mobile -->|"HTTPS"| Traefik
    Traefik -->|"Serves SPA"| Frontend
    Traefik -->|"Routes REST"| ApiGateway
    Frontend -->|"HTTPS/REST"| ApiGateway

    %% Async via RabbitMQ
    ApiGateway -.->|"publish events"| RabbitMQ

    RabbitMQ -.-> AuthSvc
    RabbitMQ -.-> ContratSvc
    RabbitMQ -.-> OperationSvc
    RabbitMQ -.-> FactureSvc
    RabbitMQ -.-> InterventionSvc
    RabbitMQ -.-> MailerSvc
    RabbitMQ -.-> WorkflowSvc

    %% Database connections
    AuthSvc -->|"SQL"| Postgres
    ContratSvc -->|"SQL"| Postgres
    OperationSvc -->|"SQL"| Postgres
    FactureSvc -->|"SQL"| Postgres
    InterventionSvc -->|"SQL"| Postgres
    MailerSvc -->|"SQL"| Postgres
    WorkflowSvc -->|"SQL"| Postgres

    %% Monitoring scrapes
    Prometheus -->|"scrapes metrics"| ApiGateway
    Prometheus -->|"scrapes metrics"| AuthSvc
    Prometheus -->|"scrapes metrics"| ContratSvc
    Prometheus -->|"scrapes metrics"| OperationSvc
    Prometheus -->|"scrapes metrics"| FactureSvc
    Prometheus -->|"scrapes metrics"| InterventionSvc
    Prometheus -->|"scrapes metrics"| MailerSvc
    Prometheus -->|"scrapes metrics"| WorkflowSvc
    Prometheus -->|"scrapes metrics"| RabbitMQ
    Prometheus -->|"scrapes metrics"| Postgres

    Grafana -->|"reads from"| Prometheus

    %% CI/CD flow
    GitHubActions -->|"build images"| DockerRegistry
    DockerRegistry -->|"deploy manifests"| Traefik
    DockerRegistry -->|"deploy manifests"| ApiGateway
    DockerRegistry -->|"deploy manifests"| AuthSvc
    DockerRegistry -->|"deploy manifests"| ContratSvc
    DockerRegistry -->|"deploy manifests"| OperationSvc
    DockerRegistry -->|"deploy manifests"| FactureSvc
    DockerRegistry -->|"deploy manifests"| InterventionSvc
    DockerRegistry -->|"deploy manifests"| MailerSvc
    DockerRegistry -->|"deploy manifests"| WorkflowSvc
    click DockerRegistry "https://github.com/yasblha/projet-facturation/blob/develop/docker-compose.yml"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef gateway fill:#90EE90,stroke:#333,stroke-width:1px
    classDef broker fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef service fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef db fill:#FFA500,stroke:#333,stroke-width:1px
    classDef monitor fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef cicd fill:#F0E68C,stroke:#333,stroke-width:1px
```
