How incubateur-ademe/plusfraichemaville-site works
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.