How vivien-parsis/handimap works
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