# dsgoficial/sap architecture

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

## Overview

##### Project Type and Purpose
- This is a full-stack application aimed at managing cartographic production. The backend, built in Node.js, handles processes such as activity distribution, production monitoring, metadata generation, and database permissions, while the frontend (in the client directory) provides a React (with TypeScript) based user interface.
- The project integrates with external systems like the FME Manager, DSGTools, and an external Authentication Service. It also supports QGIS clients (“SAP Operador” and “SAP Gerente”), highlighting the need for clear external integration points.

##### Main Components
a. Client (Frontend):
- Located in the “client” directory with source components, routes, hooks, and feature-based modules (dashboard, map, grid, activities, auth, etc.).
- Technologies: React/TypeScript, Vite (as evident from vite.config.ts and related configs), and libraries like Axios (in “lib/axios.ts”).
b. Server (Backend):
- Located under the “server” directory, organized by domain (acompanhamento, authentication, gerencia, login, produção, microcontrole, etc.).
- The server also contains database management (SQL scripts in server/src/database) and utilities (for error handling, logging, etc.).
- Key functionalities include authentication, production control, and interfacing with external services.
c. Database:
- While not directly included as a codebase, the numerous SQL scripts in folders such as “er” and “server/src/database” indicate reliance on PostgreSQL with geospatial extensions.
d. External Integrations:
- Integration with external services like FME Manager, DSGTools, and a separate Authentication Service is explicitly mentioned in the README.
- QGIS clients (for both operators and managers) are also integrated with the system.

##### Relationships and Interactions
- External authentication should be represented as well, with the backend either delegating or validating tokens via the external Authentication Service.
- External services (e.g., Gerenciador_FME, DSGTools) should be separate nodes connected to the backend, showing integration points.
- Where applicable, denote feedback loops such as error handling, logging, and asynchronous operations (noted in the “utils/async_handler_with_queue.js” and logger modules).

##### Architectural Patterns or Design Principles
- The codebase is organized in a feature-driven (modular) approach on both client and server, which promotes separation of concerns.
- The client uses modern component-based patterns (e.g., for dashboards, maps, grids), while the server is segmented by functionality (authentication, production, etc.), resembling a microservice-like modular monolith.
- Use of routing, middleware for error handling, and clear domain separation (activities, production, metadata) are important principles reflected in the file tree.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Client (React/Vite)"
        A["Client UI"]:::frontend
        D["Dashboard Module"]:::frontend
        M["Map Module"]:::frontend
        G["Grid Module"]:::frontend
        AC["Activities Module"]:::frontend
        AU["Authentication Module"]:::frontend
        MC["MicroControl Module"]:::frontend
        P["PIT Module"]:::frontend
        S["Subphases Module"]:::frontend
    end

    %% Backend Layer
    subgraph "Server (Node.js API)"
        B["API Gateway"]:::backend
        ACC["Acompanhamento Module"]:::backend
        ASrv["Authentication Module"]:::backend
        GER["Gerencia Module"]:::backend
        L["Login Module"]:::backend
        META["Metadados Module"]:::backend
        MC_srv["Microcontrole Module"]:::backend
        PER["Perigo Module"]:::backend
        PROD["Producao Module"]:::backend
        PROJ["Projeto Module"]:::backend
        RH["RH Module"]:::backend
        USR["Usuario Module"]:::backend
        DB["PostgreSQL Database"]:::database
    end

    %% External Integration Layer
    subgraph "External Integrations"
        ExtAuth["External Authentication Service"]:::external
        FME["FME Integration"]:::external
        DSG["DSGTools"]:::external
        QO["QGIS – Operador"]:::external
        QG["QGIS – Gerente"]:::external
    end

    %% Inter-layer Communications
    A -->|"APIrequest"| B
    D -->|"APIrequest"| B
    M -->|"APIrequest"| B
    G -->|"APIrequest"| B
    AC -->|"APIrequest"| B
    AU -->|"APIrequest"| B
    MC -->|"APIrequest"| B
    P -->|"APIrequest"| B
    S -->|"APIrequest"| B

    B -->|"dbQuery"| DB

    %% Backend module interactions
    B --> ACC
    B --> ASrv
    B --> GER
    B --> L
    B --> META
    B --> MC_srv
    B --> PER
    B --> PROD
    B --> PROJ
    B --> RH
    B --> USR

    %% External Integration communications
    B -->|"validate"| ExtAuth
    B -->|"exchange"| FME
    B -->|"exchange"| DSG
    GER -->|"integrate"| QO
    GER -->|"integrate"| QG

    %% Click Events (Frontend)
    click A "https://github.com/dsgoficial/sap/tree/master/client/"
    click D "https://github.com/dsgoficial/sap/tree/master/client/src/features/dashboard/"
    click M "https://github.com/dsgoficial/sap/tree/master/client/src/features/map/"
    click G "https://github.com/dsgoficial/sap/tree/master/client/src/features/grid/"
    click AC "https://github.com/dsgoficial/sap/tree/master/client/src/features/activities/"
    click AU "https://github.com/dsgoficial/sap/tree/master/client/src/features/auth/"
    click MC "https://github.com/dsgoficial/sap/tree/master/client/src/features/microControl/"
    click P "https://github.com/dsgoficial/sap/tree/master/client/src/features/pit/"
    click S "https://github.com/dsgoficial/sap/tree/master/client/src/features/subphases/"

    %% Click Events (Backend)
    click B "https://github.com/dsgoficial/sap/tree/master/server/src/server/"
    click ACC "https://github.com/dsgoficial/sap/tree/master/server/src/acompanhamento/"
    click ASrv "https://github.com/dsgoficial/sap/tree/master/server/src/authentication/"
    click GER "https://github.com/dsgoficial/sap/tree/master/server/src/gerencia/"
    click L "https://github.com/dsgoficial/sap/tree/master/server/src/login/"
    click META "https://github.com/dsgoficial/sap/tree/master/server/src/metadados/"
    click MC_srv "https://github.com/dsgoficial/sap/tree/master/server/src/microcontrole/"
    click PER "https://github.com/dsgoficial/sap/tree/master/server/src/perigo/"
    click PROD "https://github.com/dsgoficial/sap/tree/master/server/src/producao/"
    click PROJ "https://github.com/dsgoficial/sap/tree/master/server/src/projeto/"
    click RH "https://github.com/dsgoficial/sap/tree/master/server/src/rh/"
    click USR "https://github.com/dsgoficial/sap/tree/master/server/src/usuario/"
    click DB "https://github.com/dsgoficial/sap/tree/master/server/src/database/"

    %% Click Events (External Integrations)
    click FME "https://github.com/dsgoficial/sap/tree/master/server/src/gerenciador_fme/"
    click QO "https://github.com/dsgoficial/sap/blob/master/server/src/gerencia/qgis_project.js"
    click QG "https://github.com/dsgoficial/sap/blob/master/server/src/gerencia/qgis_project.js"

    %% Styles
    classDef frontend fill:#A3D8F4,stroke:#333,stroke-width:2px;
    classDef backend fill:#F6A5A5,stroke:#333,stroke-width:2px;
    classDef database fill:#A4DE02,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
    classDef external fill:#E3B3F7,stroke:#333,stroke-width:2px,stroke-dasharray: 3 3;
```
