# vivien-parsis/handimap architecture

> Architecture diagram of the GitHub repository vivien-parsis/handimap, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vivien-parsis/handimap
- Repository: https://github.com/vivien-parsis/handimap

## Overview

##### Project type and purpose
- This is a full-stack web application (“Handi’Map”) with:
- A React/Vite frontend (SPA)
- A Node.js/Express backend (REST API)
- An external PostgreSQL database
- Cloudinary for media storage
- Docker Compose orchestration

##### File structure
- Top-level dirs:
- backend/ (Node/Express app with controllers, services, models, middlewares, routes, config)
- front-end/ (React app under src/, assets/, CSS modules, config, built with Vite, served via nginx)
- Configuration & infra:
- docker-compose.yml (defines frontend & backend services)
- Dockerfiles in backend/ and front-end/
- .env templates for secrets, API URLs
- Testing and CI:
- backend/tests/ (Jest)
- .github/workflows/ci.yml

##### Key architecture insights from README
- SPA interacts with a REST API
- Data persistence in PostgreSQL (schema.sql defines tables/relations)
- Cloudinary SDK used by backend for image uploads
- Docker Compose recommended for deployment

##### Main components & interactions (to include
a. User’s Browser (Client)
b. Frontend Service (React + nginx)
c. Backend Service (Node.js + Express)
d. PostgreSQL Database (external)
e. Cloudinary (external media service)
f. Docker Compose network (internal)

##### Component relationships & data flow
- Browser → HTTP(S) → Frontend (nginx serves static assets + SPA)
- SPA → REST API calls → Backend (port 4000)
- Backend → SQL queries → PostgreSQL
- Backend → Cloudinary SDK/API → Cloudinary
- Middleware chain inside Backend: logging → CORS → auth → rate-limiting → controllers → services → models

##### Architectural patterns & design principles
- Frontend: Single-Page Application, component-based, CSS modules
- Backend: Layered MVC
- Controllers handle HTTP routes
- Services contain business logic
- Models map to DB tables
- Middlewares handle cross-cutting concerns (auth, helmet, cors, logging, rateLimiter, upload)
- API documentation with Swagger (swagger.config.js)

##### Technologies & frameworks
- Frontend: React, Vite, JSX, CSS Modules, nginx
- Backend: Node.js, Express, pg or Sequelize (models), Jest, Swagger
- Infra: Docker, Docker Compose, GitHub Actions CI, .env configuration

##### Essential elements to capture
- Clear labels on all nodes (e.g., “React SPA (Vite)”, “Express API”)
- Middleware chain or annotate “Auth + RateLimiter + CORS” on the API boundary
- Visual grouping of Docker Compose services and network

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Client Layer"
        User(["User Browser"]):::client
    end

    subgraph "Docker Compose Network"
        direction TB

        subgraph "Presentation Layer"
            direction TB
            subgraph "front-end/"
                direction TB
                SPA["React SPA (Vite)"]:::frontend
                Entry["src/index.jsx"]:::frontend
                AppComp["src/App.jsx"]:::frontend
                ViteCfg["vite.config.js"]:::frontend
                DockerFE["dockerfile"]:::frontend
            end
            NGINX["nginx (80/443)"]:::frontend
        end

        subgraph "API Layer"
            direction TB
            subgraph "backend/"
                direction TB
                API["Express API (4000)\nAuth+CORS+RateLimiter"]:::backend
                ServerJS["server.js"]:::backend
                AppJS["app.js"]:::backend
                Controllers["controllers/*.controller.js"]:::backend
                Services["services/*.service.js"]:::backend
                Models["models/*.model.js"]:::backend
                Routes["routes/*.route.js"]:::backend
                Middlewares["middlewares/*.middleware.js"]:::backend
                ConfigDB["config/db.config.js"]:::backend
                SchemaSQL["schema.sql"]:::backend
                CloudCfg["config/cloudinary.config.js"]:::backend
                ServerCfg["config/server.config.js"]:::backend
                SwaggerCfg["config/swagger.config.js"]:::backend
                DockerBE["dockerfile"]:::backend
            end
        end
    end

    subgraph "Data Layer"
        DB["PostgreSQL DB"]:::db
    end

    subgraph "External Services"
        CLOUD["Cloudinary"]:::external
    end

    subgraph "Infrastructure"
        DC["docker-compose.yml"]:::infra
        CI[".github/workflows/ci.yml"]:::infra
    end

    %% Connections
    User -->|"HTTP(S)"| NGINX
    NGINX -->|"Serves SPA"| SPA
    SPA -->|"REST API calls"| API
    API -->|"SQL queries"| DB
    API -->|"Image upload"| CLOUD
    DC --> NGINX
    DC --> API

    %% Click Events
    click SPA "https://github.com/vivien-parsis/handimap/tree/main/front-end/"
    click Entry "https://github.com/vivien-parsis/handimap/blob/main/front-end/src/index.jsx"
    click AppComp "https://github.com/vivien-parsis/handimap/blob/main/front-end/src/App.jsx"
    click ViteCfg "https://github.com/vivien-parsis/handimap/blob/main/front-end/vite.config.js"
    click DockerFE "https://github.com/vivien-parsis/handimap/tree/main/front-end/dockerfile"
    click NGINX "https://github.com/vivien-parsis/handimap/blob/main/front-end/nginx.conf"
    click API "https://github.com/vivien-parsis/handimap/tree/main/backend/"
    click ServerJS "https://github.com/vivien-parsis/handimap/blob/main/backend/server.js"
    click AppJS "https://github.com/vivien-parsis/handimap/blob/main/backend/app.js"
    click Controllers "https://github.com/vivien-parsis/handimap/blob/main/backend/controllers/*.controller.js"
    click Services "https://github.com/vivien-parsis/handimap/blob/main/backend/services/*.service.js"
    click Models "https://github.com/vivien-parsis/handimap/blob/main/backend/models/*.model.js"
    click Routes "https://github.com/vivien-parsis/handimap/blob/main/backend/routes/*.route.js"
    click Middlewares "https://github.com/vivien-parsis/handimap/blob/main/backend/middlewares/*.middleware.js"
    click ConfigDB "https://github.com/vivien-parsis/handimap/blob/main/backend/config/db.config.js"
    click SchemaSQL "https://github.com/vivien-parsis/handimap/blob/main/backend/schema.sql"
    click CloudCfg "https://github.com/vivien-parsis/handimap/blob/main/backend/config/cloudinary.config.js"
    click ServerCfg "https://github.com/vivien-parsis/handimap/blob/main/backend/config/server.config.js"
    click SwaggerCfg "https://github.com/vivien-parsis/handimap/blob/main/backend/config/swagger.config.js"
    click DockerBE "https://github.com/vivien-parsis/handimap/tree/main/backend/dockerfile"
    click DC "https://github.com/vivien-parsis/handimap/blob/main/docker-compose.yml"
    click CI "https://github.com/vivien-parsis/handimap/blob/main/.github/workflows/ci.yml"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085
    classDef backend fill:#d4edda,stroke:#155724,color:#155724
    classDef db fill:#fff3cd,stroke:#856404,color:#856404
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef client fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef infra fill:#d1ecf1,stroke:#0c5460,color:#0c5460
```
