# 841723/locatopedia architecture

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

- Interactive diagram: https://gitdiagram.com/841723/locatopedia
- Repository: https://github.com/841723/locatopedia

## Overview

##### Project type and purpose
- Type: Full-stack web application
- Purpose: A wiki-style article platform with geospatial tooling (“dggs”) and OAuth-based user accounts.
- Key stacks: React/Vite on the front end; Node.js/Express on the back end; a Python microservice for DGGS tools; PostgreSQL for persistence; Docker Compose for orchestration; Nginx for static hosting.

##### Top-level components
- Client (Browser)
- Frontend container (“www”):
- Vite dev server (dev mode) or
- Nginx + static assets (prod mode)
- Backend container (“api”): Node.js/Express
- DGGS microservice container (“dggstools”): Python/Flask
- Database container: PostgreSQL
- Data volume: DB dumps and backups
- External services: Google OAuth, Locatopedia API

##### Relationships & data flows
- Browser ←→ Frontend
- User navigates pages, invokes searches, submits articles.
- Frontend → Backend (REST/JSON)
- Authentication calls (Google OAuth redirect)
- Article CRUD endpoints (`/routes_wiki*`)
- DGGS processing requests (`/routes_dggs*`)
- Backend ↔ PostgreSQL
- SQL scripts and migrations (`init_tables.sql`, `sql-examples/*`)
- Persistent storage of articles, versions, users, metadata
- Backend → DGGS microservice
- HTTP calls to `app.py` endpoints in `services/dggstools`
- Backend → External OAuth
- Google OAuth flow via `googleOAuth.js`
- Backend → Locatopedia
- Geospatial lookups via `locatopedia.js`

##### Architectural patterns & design principles
- Layered architecture: Presentation (React) → API (Express) → Data (PostgreSQL)
- Microservice: DGGS tooling is isolated in its own service/container.
- 12-factor app + containerization: each major component in its own Docker container.
- Context + hooks in front end: global state managed via React Context (`src/context/*`), reusable fetch hooks (`src/hooks/useFetch.jsx`).
- Environment-driven configuration: `.env.example` in both frontend/backend; Docker Compose for orchestration (`compose.yml` files).

##### Final checklist
- [ ] Label every container/service, port, and endpoint
- [ ] External dependencies clearly separated
- [ ] Note the development vs. production variants (Vite dev server vs. Nginx)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Browser["Client Browser"]:::external

    %% Frontend Container
    subgraph "Frontend Container (www-1)" 
        direction TB
        Frontend["Frontend<br/>(Port: 80/3000)"]:::frontend
        Vite["Vite Dev Server"]:::frontend
        Nginx["Nginx + Static Assets"]:::frontend
    end

    %% Backend Container
    subgraph "Backend Container (api-1)"
        direction TB
        Backend["Node.js/Express<br/>(Port: 3001)"]:::backend
        Index["index.js"]:::backend
        OAuthMod["googleOAuth.js"]:::backend
        GeoMod["locatopedia.js"]:::backend
        Utils["data.js / utils.js"]:::backend
        subgraph "Routes"
            direction TB
            Wiki["routes_wiki.js"]:::backend
            AuthWiki["routes_wiki_auth.js"]:::backend
            DGGSRoutes["routes_dggs.js"]:::backend
        end
    end

    %% DGGS Microservice
    subgraph "DGGS Microservice (dggstools-1)"
        direction TB
        DGGSService["Flask Service<br/>(Port: 5000)"]:::micro
        AppPy["app.py"]:::micro
        CommonLib["lib/common.py"]:::micro
        ReqTxt["requirements.txt"]:::micro
    end

    %% Database & Volume
    DB["PostgreSQL"]:::db
    Volume["Data Volume<br/>(/data)"]:::volume

    %% External Services
    Google["Google OAuth"]:::external
    Locato["Locatopedia API"]:::external

    %% Orchestration
    Compose["Docker Compose"]:::backend

    %% Connections
    Browser -->|HTTP GET/POST| Frontend
    Frontend -->|REST/JSON| Backend
    Backend -->|SQL| DB
    DB -->|Backups| Volume
    Backend -->|HTTP| DGGSService
    Backend -->|OAuth Redirect/Token| Google
    Backend -->|HTTP API| Locato
    Compose --> Frontend
    Compose --> Backend
    Compose --> DGGSService
    Compose --> DB

    %% Click Events - Frontend
    click Frontend "https://github.com/841723/locatopedia/tree/main/frontend/"
    click Vite "https://github.com/841723/locatopedia/blob/main/frontend/vite.config.js"
    click Nginx "https://github.com/841723/locatopedia/blob/main/frontend/nginx.conf"
    click Frontend "https://github.com/841723/locatopedia/tree/main/frontend/Dockerfile"
    click Frontend "https://github.com/841723/locatopedia/blob/main/frontend/.env.example"
    click Frontend "https://github.com/841723/locatopedia/tree/main/frontend/src/"
    click Frontend "https://github.com/841723/locatopedia/tree/main/frontend/public/"

    %% Click Events - Backend
    click Backend "https://github.com/841723/locatopedia/tree/main/backend/"
    click Backend "https://github.com/841723/locatopedia/tree/main/backend/Dockerfile"
    click Compose "https://github.com/841723/locatopedia/blob/main/backend/compose.yml"
    click Index "https://github.com/841723/locatopedia/blob/main/backend/index.js"
    click OAuthMod "https://github.com/841723/locatopedia/blob/main/backend/googleOAuth.js"
    click GeoMod "https://github.com/841723/locatopedia/blob/main/backend/locatopedia.js"
    click Utils "https://github.com/841723/locatopedia/blob/main/backend/data.js"
    click Utils "https://github.com/841723/locatopedia/blob/main/backend/utils.js"
    click Wiki "https://github.com/841723/locatopedia/blob/main/backend/routes_wiki.js"
    click AuthWiki "https://github.com/841723/locatopedia/blob/main/backend/routes_wiki_auth.js"
    click DGGSRoutes "https://github.com/841723/locatopedia/blob/main/backend/routes_dggs.js"

    %% Click Events - DGGS
    click DGGSService "https://github.com/841723/locatopedia/tree/main/backend/services/dggstools/"
    click AppPy "https://github.com/841723/locatopedia/blob/main/backend/services/dggstools/app.py"
    click CommonLib "https://github.com/841723/locatopedia/blob/main/backend/services/dggstools/lib/common.py"
    click ReqTxt "https://github.com/841723/locatopedia/blob/main/backend/services/dggstools/requirements.txt"
    click DGGSService "https://github.com/841723/locatopedia/tree/main/backend/services/dggstools/Dockerfile"

    %% Click Events - Database & SQL
    click DB "https://github.com/841723/locatopedia/blob/main/init_tables.sql"
    click DB "https://github.com/841723/locatopedia/tree/main/sql-examples/"
    click Volume "https://github.com/841723/locatopedia/tree/main/backend/data/"

    %% Click Events - Compose Root
    click Compose "https://github.com/841723/locatopedia/blob/main/compose.yml"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,color:#000;
    classDef backend fill:#87CEFA,stroke:#000,color:#000;
    classDef micro fill:#98FB98,stroke:#000,color:#000;
    classDef db fill:#FFA500,stroke:#000,color:#000;
    classDef external fill:#D3D3D3,stroke:#000,color:#000;
    classDef volume fill:#F5DEB3,stroke:#000,color:#000;
```
