# anct-cnum/api-conseiller-numerique architecture

> Architecture diagram of the GitHub repository anct-cnum/api-conseiller-numerique, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anct-cnum/api-conseiller-numerique
- Repository: https://github.com/anct-cnum/api-conseiller-numerique

## Overview

##### Project Type and Purpose
- This is a backend API built on the Feathers framework that serves as the application’s main server. Its purpose is to provide a real-time API integrated with various services such as authentication, data exports, email sending, and more. Its integration with MongoDB is core (with PostgreSQL as an optional secondary database) and there are many administrative and data-processing tools.
- The README emphasizes setup for MongoDB (and optionally PostgreSQL), API startup, and testing. This confirms that the project is centered on a backend service offering REST and real-time functionalities using Feathers.

##### File Structure for Architectural Insights
- Top-Level components include:
- Configuration files (e.g., config/, .eslintrc.json, package.json) which indicate environment-specific setups (default, production, test).
- The src/ directory which holds the application code. This directory is further split into key areas:
▸ Core Application Files: app.js, index.js, logger.js, mailer.js, and the MongoDB connection (mongodb.js).
▸ Services: Organized under src/services with many domain areas (conseillers, coordinateurs, cras, structures, users, stats, and more). This suggests a microservices-like or modular service architecture within a Feathers application.
▸ Emails: In src/emails, with many templates (using mjml.ejs) and corresponding JS files, indicating an extensive email notification subsystem.
▸ Tools and Admin Scripts: Located in src/tools (with subdirectories for admin tasks, exports, jobs, population, scripts, etc.) which are used for maintenance, data processing, or administrative operations.
▸ Common Utilities and Repositories: In src/common, supporting shared logic and data access (like feathers.utils.js, document templates, and repositories).
- Public: Likely static assets.
- Tests appear under test/ and include integration and unit tests which highlight robust testing strategy.

- The presence of numerous GitHub workflow files (in .github/workflows) points to CI/CD practices including linting, dependency management, and automated deployments (to production, demo, etc.).

a. Main Components to Represent:
- API Server (Core Application Layer): Represented by the Feathers app (src/app.js, src/index.js).
- Services Modules: Each major domain (conseillers, coordinateurs, cras, structures, users, etc.) should be a separate component. Group them or show them as distinct microservice blocks under “Services.”
- Email System: Separate component detailing email templates, notification modules, and hooks used to trigger email events.
- Tools/Administration: A section for admin scripts and maintenance tasks (located under src/tools) which interact with the core database or trigger certain jobs.
- Database(s):
▸ Primary: MongoDB – indicated by the src/mongodb.js and related configuration.
▸ Optional: PostgreSQL – as described in the README, using Docker instructions.
- External Interfaces: Indicate integration with external systems (like CleverCloud configurations in the clevercloud folder, and possible external APIs in src/utils/entreprise.api.gouv.js).

b. Relationships and Data Flows:
- Client/UI (or other consumers) interact with the API server.
- The API server routes requests to the appropriate Feathers services.
- Services interact with the MongoDB database (via repositories and direct calls in src/services).
- Some services may trigger email flows and administrative scripts.
- The Tools/Jobs layer may run periodically (e.g., via cron or Docker jobs as seen in the clevercloud and src/tools/jobs directories) to process or export data.

c. Architectural Patterns:
- Modular Design: The services are separated by domain (using Feathers services and hooks) ensuring clear separation of concerns.
- Real-Time & RESTful API: Built on Feathers which supports both REST and real-time (websocket) communications.
- Dependency Injection & Utility Libraries: The presence of common utilities and repositories indicate reusability and adherence to DRY principles.
- CI/CD and Automated Testing: Indicated by GitHub workflows and extensive test directories.

d. Relevant Technologies and Frameworks:
- FeathersJS as the main framework for real-time API.
- MongoDB (and optionally PostgreSQL) as the primary data storage.
- Docker containerization for running the databases.
- Node.js / npm for the runtime environment and dependency management.
- Email templating via MJML integrated in the emails section.
- GitHub Actions for deployment and integration (CI/CD).

- API Server (Feathers Application)
- Each main Service Module (e.g., Conseillers, Coordinateurs, Structures, Cras, Stats, Users)
- Email System (detailing both admin and user email templates)
- Tools / Admin Scripts (grouped by purpose if needed)
- Primary Database (MongoDB) and optional Secondary Database (PostgreSQL)
- External Integrations (e.g., CleverCloud, external APIs)
- Every component and data flow is clearly labeled to capture dependency relationships and interactions.

## Diagram (Mermaid)

```mermaid
graph TD
    Client("Client/UI"):::client

    subgraph "Core Layer"
        Config("Config & Environment")
        API_Server("API Server (Feathers Application)")
    end

    subgraph "Services Layer"
        Conseillers("Conseillers Service")
        Coordinateurs("Coordinateurs Service")
        CRAS("CRAS Service")
        Structures("Structures Service")
        Users("Users Service")
        Stats("Stats Service")
        Additional("Additional Services")
    end

    subgraph "Email System"
        Email("Email Notifications & Templates")
    end

    subgraph "Tools / Administration"
        Tools("Admin Scripts & Tools")
    end

    subgraph "Database Layer"
        MongoDB("MongoDB")
        PostgreSQL("PostgreSQL (Optional)")
    end

    subgraph "External Integration"
        Clever("CleverCloud Config")
        Entreprise("Entreprise API Integration")
    end

    subgraph "CI/CD & Testing"
        Workflows("GitHub Workflows")
        Tests("Test Suites")
    end

    %% Connections
    Client -->|"requests"| API_Server
    Config -->|"configures"| API_Server
    API_Server -->|"routesTo"| Conseillers
    API_Server -->|"routesTo"| Coordinateurs
    API_Server -->|"routesTo"| CRAS
    API_Server -->|"routesTo"| Structures
    API_Server -->|"routesTo"| Users
    API_Server -->|"routesTo"| Stats
    API_Server -->|"routesTo"| Additional
    API_Server -->|"triggers"| Tools
    API_Server -->|"integrates"| Entreprise
    API_Server -->|"integrates"| Clever

    %% Services to Database
    Conseillers -->|"uses"| MongoDB
    Coordinateurs -->|"uses"| MongoDB
    CRAS -->|"uses"| MongoDB
    Structures -->|"uses"| MongoDB
    Users -->|"uses"| MongoDB
    Stats -->|"uses"| MongoDB
    Additional -->|"uses"| MongoDB

    %% Services triggering Email notifications
    Conseillers -->|"notifies"| Email
    Users -->|"notifies"| Email

    %% Tools interactions
    Tools -->|"manages"| MongoDB
    Tools -->|"exportsDataTo"| API_Server

    %% CI/CD & Testing support
    Workflows ---|"builds"| Config
    Tests ---|"validates"| API_Server

    %% Optional Database
    API_Server ---|"optionalDB"| PostgreSQL

    %% Styles
    classDef client fill:#FFE0B2,stroke:#F57C00,stroke-width:2px;
    classDef core fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef service fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
    classDef email fill:#FFD54F,stroke:#FF6F00,stroke-width:2px;
    classDef tool fill:#D1C4E9,stroke:#4A148C,stroke-width:2px;
    classDef db fill:#FFCDD2,stroke:#B71C1C,stroke-width:2px;
    classDef external fill:#B2EBF2,stroke:#006064,stroke-width:2px;
    classDef cicd fill:#DCEDC8,stroke:#33691E,stroke-width:2px;

    class Client client;
    class Config,API_Server core;
    class Conseillers,Coordinateurs,CRAS,Structures,Users,Stats,Additional service;
    class Email email;
    class Tools tool;
    class MongoDB,PostgreSQL db;
    class Clever,Entreprise external;
    class Workflows,Tests cicd;

    %% Click Events
    click API_Server "https://github.com/anct-cnum/api-conseiller-numerique/blob/main/src/app.js"
    click API_Server "https://github.com/anct-cnum/api-conseiller-numerique/blob/main/src/index.js"
    click Config "https://github.com/anct-cnum/api-conseiller-numerique/tree/main/config/"
    click Config "https://github.com/anct-cnum/api-conseiller-numerique/blob/main/package.json"
    click Conseillers "https://github.com/anct-cnum/api-conseiller-numerique/tree/main/src/services/conseillers"
    click Coordinateurs "https://github.com/anct-cnum/api-conseiller-numerique/tree/main/src/services/coordinateurs"
    click CRAS "https://github.com/anct-cnum/api-conseiller-numerique/tree/main/src/services/cras"
    click Structures "https://github.com/anct-cnum/api-conseiller-numerique/tree/main/src/services/structures"
    click Users "https://github.com/anct-cnum/api-conseiller-numerique/tree/main/src/services/users"
    click Stats "https://github.com/anct-cnum/api-conseiller-numerique/tree/main/src/services/stats"
    click Email "https://github.com/anct-cnum/api-conseiller-numerique/tree/main/src/emails"
    click Tools "https://github.com/anct-cnum/api-conseiller-numerique/tree/main/src/tools"
    click MongoDB "https://github.com/anct-cnum/api-conseiller-numerique/blob/main/src/mongodb.js"
    click Clever "https://github.com/anct-cnum/api-conseiller-numerique/tree/main/clevercloud"
    click Entreprise "https://github.com/anct-cnum/api-conseiller-numerique/blob/main/src/utils/entreprise.api.gouv.js"
    click Workflows "https://github.com/anct-cnum/api-conseiller-numerique/tree/main/.github/workflows"
    click Tests "https://github.com/anct-cnum/api-conseiller-numerique/tree/main/test/"
```
