# pnx-si/geonature architecture

> Architecture diagram of the GitHub repository pnx-si/geonature, 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/pnx-si/geonature
- Repository: https://github.com/pnx-si/geonature

## Overview

##### Project Type and Purpose
- The application (GeoNature V2) is a full‑stack solution built with Python/Flask on the backend and Angular/Leaflet on the frontend.
- It works as a data entry and synthesis system – collecting observations according to various protocols (“faune” and “flore”), integrating external modules (such as UsersHub for user management, TaxHub for taxonomy, Nomenclature API, etc.), and providing an interface for synthesis and external dissemination.
- Its modular design allows extending the system with additional protocols via modules.

##### Main Components
- Backend Application: The core lies in the “backend” directory and the “geonature” package. It contains many sub-components:
- Core domain modules (gn_commons, gn_meta, gn_monitoring, gn_permissions, gn_profiles, gn_synthese, etc.), each responsible for a different domain (administration, permissions, synthesis, import logic, metadata, notifications, and more).
- A “dependencies” folder that shows integration of external modules (e.g., Habref-api-module, Nomenclature-api-module, TaxHub, UsersHub/authentification-module, etc.) which indicate further modularity and integration points with external systems.
- Command Line tools and Celery tasks for asynchronous operation.
- Frontend Application: Found under “frontend”. It is built with Angular and integrated with advanced UI components (using Bootstrap, Leaflet for maps, and custom modules for imports, syntheses, and user interactions). It has testing infrastructure with Cypress for end-to-end tests.
- Database Layer: While not explicitly named as “DB” folders, the backend contains extensive migration folders (alembic migrations in “backend/geonature/migrations”), SQL scripts (in the “data” directory), and configurations. This portion represents the relational DB structure and its evolution.
- External Modules and Services: The project is integrated with external systems such as:
- UsersHub for centralized user management.
- TaxHub, Nomenclature API, and others as separate submodules (found in “contrib” and through Git submodules).
- Additional modules (like validation, monitoring, export/import modules) separated as components integrated via the modular system.
- DevOps/Deployment: Dockerfiles, Makefile, and continuous integration files under “.github/workflows” show CI/CD integration plus Dockerized deployment.

##### Relationships and Interactions
- The Frontend communicates with the Backend over APIs. The architecture reflects a clear separation between presentation (Angular) and business logic (Flask).
- The Backend acts as the central orchestrator managing data from different protocols, invoking Celery tasks for asynchronous processing, and handling complex business logic (for instance, imports and notifications).
- The external modules (UsersHub, TaxHub, etc.) interact with the backend either as dependencies or with their own API endpoints as part of a microservices-like architecture.
- The database component is handled through migration scripts and interacts with the backend ORM models (SQLAlchemy likely through the Utils-Flask-SQLAlchemy modules).

##### Architectural Patterns and Design Principles
- Layered Pattern: Separation between controllers (Flask routes, Angular components), services (backend tasks, import actions), and data-access (models, migrations, repositories).
- Microservices inspiration (for external modules): Some functionality is separated into modules that can be developed and maintained independently.
- Use of asynchronous processing: Celery tasks indicate a separation of long-running or background jobs.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE_Angular["Frontend (Angular & Leaflet)"]:::frontend
        FE_Cypress["End-to-End Testing (Cypress)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        BA_Flask["Backend (Flask & Celery)"]:::backend
        subgraph "Core Domain Modules"
            CORE_Commons["GN Commons"]:::module
            CORE_Meta["GN Meta"]:::module
            CORE_Monitoring["GN Monitoring"]:::module
            CORE_Permissions["GN Permissions"]:::module
            CORE_Profiles["GN Profiles"]:::module
            CORE_Synthese["GN Synthèse"]:::module
        end
        ASYNC["Celery Tasks & CLI Tools"]:::backend
    end

    %% External Modules & Integrations
    subgraph "External Modules"
        EXT_UsersHub["UsersHub"]:::external
        EXT_TaxHub["TaxHub"]:::external
        EXT_Habref["Habref-api-module"]:::external
    end

    %% Database Layer
    subgraph "Database Layer"
        DB["Database (Migrations & SQL)"]:::database
    end

    %% DevOps & Deployment
    subgraph "DevOps/Deployment"
        DEV["CI/CD Pipelines & Docker"]:::devops
    end

    %% Connections
    FE_Angular -->|"HTTP_API"| BA_Flask
    BA_Flask --> CORE_Commons
    BA_Flask --> CORE_Meta
    BA_Flask --> CORE_Monitoring
    BA_Flask --> CORE_Permissions
    BA_Flask --> CORE_Profiles
    BA_Flask --> CORE_Synthese
    BA_Flask --> ASYNC
    BA_Flask --> EXT_UsersHub
    BA_Flask --> EXT_TaxHub
    BA_Flask --> EXT_Habref
    BA_Flask -- "ORM" --- DB

    %% Styles
    classDef frontend fill:#A2D9CE,stroke:#1E8449,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef module fill:#85C1E9,stroke:#2874A6,stroke-width:2px;
    classDef external fill:#F5CBA7,stroke:#D35400,stroke-width:2px;
    classDef database fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef devops fill:#AED6F1,stroke:#2471A3,stroke-width:2px;

    %% Click Events
    click BA_Flask "https://github.com/pnx-si/geonature/tree/master/backend/geonature"
    click CORE_Commons "https://github.com/pnx-si/geonature/tree/master/backend/geonature/core/gn_commons"
    click CORE_Meta "https://github.com/pnx-si/geonature/tree/master/backend/geonature/core/gn_meta"
    click CORE_Monitoring "https://github.com/pnx-si/geonature/tree/master/backend/geonature/core/gn_monitoring"
    click CORE_Permissions "https://github.com/pnx-si/geonature/tree/master/backend/geonature/core/gn_permissions"
    click CORE_Profiles "https://github.com/pnx-si/geonature/tree/master/backend/geonature/core/gn_profiles"
    click CORE_Synthese "https://github.com/pnx-si/geonature/tree/master/backend/geonature/core/gn_synthese"
    click ASYNC "https://github.com/pnx-si/geonature/blob/master/backend/geonature/celery_app.py"
    click EXT_UsersHub "https://github.com/pnx-si/geonature/tree/master/backend/dependencies/UsersHub"
    click EXT_TaxHub "https://github.com/pnx-si/geonature/tree/master/backend/dependencies/TaxHub"
    click EXT_Habref "https://github.com/pnx-si/geonature/tree/master/backend/dependencies/Habref-api-module"
    click DB "https://github.com/pnx-si/geonature/tree/master/backend/geonature/migrations"
    click FE_Angular "https://github.com/pnx-si/geonature/tree/master/frontend"
    click FE_Cypress "https://github.com/pnx-si/geonature/tree/master/frontend/cypress"
    click DEV "https://github.com/pnx-si/geonature/tree/master/.github/workflows"
```
