# incubateur-ademe/plusfraichemaville-site architecture

> Architecture diagram of the GitHub repository incubateur-ademe/plusfraichemaville-site, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/incubateur-ademe/plusfraichemaville-site
- Repository: https://github.com/incubateur-ademe/plusfraichemaville-site

## Overview

##### Project Type and Purpose
- This is a full-stack web application built for Plus fraîche ma ville – a platform designed to help local governments select sustainable urban cooling solutions.
- It is implemented using Next.js (with the App router and heavy usage of Server Components) and integrates tightly with an external CMS (Strapi) for content.
- The project also includes a database layer managed through Prisma migrations and integrations with several external services (e.g., HubSpot, Mattermost, Brevo, Ragtime, etc.).

##### Analyzing the File Structure
- The top-level directories (such as "src", "public", "prisma", and "scripts") indicate clear separations:
- "src": Contains the bulk of React components, pages (divided between public static pages and authenticated/private pages), form schemas, and API endpoints.
- "prisma": Stores database schema and migration files, which shows that the application uses Prisma as an ORM to manage a relational database.
- "scripts": Contains scripts for background jobs and one-off data operations (for example, to sync data or prepare statistics).
- The presence of Next.js configuration files (next.config.js, tailwind.config.js) and build configuration (tsconfig.json, package.json) further validates a full-stack Next.js application.

##### Main Components of the System
a. Frontend (Next.js Application)
- UI components and pages under "src/app" represent both public and private (authenticated) areas.
- Components are modularized in "src/components" (agent conversationnel, annuaire, estimation, fiche-solution, etc.) to build the user interface.
- Uses Server Components extensively for improved performance and rendering.
b. Backend/API Layer
- API routes exist under "src/app/api" to handle authentication (using NextAuth), data fetching, and server-side actions.
- Server actions and business logic reside in "src/actions" which manage operations for users, projects, and content.
c. Database Layer
- Managed through Prisma (with schema in "prisma/schema.prisma" and migration scripts).
- Represents the persistent data storage (user data, project details, content metadata) and operates behind the scenes.
d. External Integrations & Services
- External CMS: The project integrates with a Strapi instance (referenced in the README and included in the repository's description) for managing the site’s content.
- Other External Services: There are dedicated modules under "src/services" (e.g., for Brevo, HubSpot, Meet Mattermost, Ragtime, and Connect) which handle integrations for marketing, messaging, and tracking.
- Authentication Service: NextAuth integration (seen in "src/app/api/auth/[...nextauth]").
- Monitoring and error tracking: Sentry configurations (sentry.client.config.ts, sentry.server.config.ts, etc.) are present.
e. Utility Libraries and Helpers
- A set of helper functions (located in "src/helpers" and "src/lib") implement shared logic such as date handling, CSV utilities, metadata management, and integration-specific helpers.

##### Relationships and Interactions
- The Frontend consumes data through the API layer built in Next.js (both via server-side requests and direct API calls).
- The API layer interacts with the database using Prisma ORM and executes business logic defined in the "actions" directories.
- Content is fetched from the external Strapi CMS, which supplies dynamic content for the site, ensuring that the frontend content is up to date.
- External services (e.g., HubSpot, Mattermost, Ragtime) are invoked via specific service modules to handle tasks such as notifications, data synchronization, and user analytics.
- Environment configurations (handled by .env files) tie together third-party APIs, the database, and the CMS credentials.

##### Architectural Patterns / Design Principles
- Separation of concerns: The application cleanly separates frontend, backend logic, and data (via Prisma).
- Modular architecture: Components, API routes, and services are organized by feature (e.g., "projets", "users", "fiche-solution") which makes the application scalable.
- Server Components and static generation: Utilized in Next.js for performance and SEO optimization.
- Clear integration points: Well-defined service layers ensure that integrations with external APIs are maintained separately from the core business logic.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Frontend (Next.js UI)"
        FE1["Next.js Pages (src/app)"]:::frontend
        FE2["UI Components (src/components)"]:::frontend
    end

    subgraph "Backend / API Layer"
        BE1["API Routes (src/app/api)"]:::backend
        BE2["Server Actions & Business Logic (src/actions)"]:::backend
        BE3["Authentication (NextAuth) (src/app/api/auth/[...nextauth])"]:::backend
    end

    subgraph "Database Layer"
        DB1["Prisma ORM (prisma)"]:::database
    end

    subgraph "External Integrations & Services"
        EXT1["CMS (Strapi)"]:::external
        EXT2["Service Modules (src/services)"]:::external
        EXT3["Monitoring (Sentry)"]:::external
    end

    subgraph "Utilities"
        UTL1["Helper Functions (src/helpers)"]:::utility
        UTL2["Shared Libraries (src/lib)"]:::utility
    end

    %% Connections
    FE1 -->|"fetchData"| BE1
    BE1 -->|"executeLogic"| BE2
    BE1 -->|"handleAuth"| BE3
    BE2 -->|"CRUD"| DB1
    BE1 -->|"getContent"| EXT1
    BE2 -->|"invokeServices"| EXT2
    BE1 -->|"logErrors"| EXT3
    BE2 -->|"useHelpers"| UTL1
    BE2 -->|"useLibs"| UTL2

    %% Click Events
    click FE1 "https://github.com/incubateur-ademe/plusfraichemaville-site/tree/main/src/app"
    click FE2 "https://github.com/incubateur-ademe/plusfraichemaville-site/tree/main/src/components"
    click BE1 "https://github.com/incubateur-ademe/plusfraichemaville-site/tree/main/src/app/api"
    click BE2 "https://github.com/incubateur-ademe/plusfraichemaville-site/tree/main/src/actions"
    click BE3 "https://github.com/incubateur-ademe/plusfraichemaville-site/blob/main/src/app/api/auth/[...nextauth]"
    click DB1 "https://github.com/incubateur-ademe/plusfraichemaville-site/tree/main/prisma"
    click EXT2 "https://github.com/incubateur-ademe/plusfraichemaville-site/tree/main/src/services"
    click UTL1 "https://github.com/incubateur-ademe/plusfraichemaville-site/tree/main/src/helpers"
    click UTL2 "https://github.com/incubateur-ademe/plusfraichemaville-site/tree/main/src/lib"

    %% Styles
    classDef frontend fill:#CFE2F3,stroke:#0B5394,stroke-width:2px;
    classDef backend fill:#D9EAD3,stroke:#38761D,stroke-width:2px;
    classDef database fill:#FCE5CD,stroke:#B45F06,stroke-width:2px;
    classDef external fill:#F4CCCC,stroke:#CC0000,stroke-width:2px;
    classDef utility fill:#EAD1DC,stroke:#9900CC,stroke-width:2px;
```
