# mitchellkolb/living-atlas architecture

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

- Interactive diagram: https://gitdiagram.com/mitchellkolb/living-atlas
- Repository: https://github.com/mitchellkolb/living-atlas

## Overview

##### Main Components

a) Client-Side (Frontend):
- React Application Container
- User Interface Components (Header, Cards, Forms)
- Visualization Component (Mapbox integration)
- Authentication Module
- API Integration Layer

b) Server-Side (Backend):
- FastAPI Application Container
- Endpoint Controllers
- Authentication Service
- File Management Service
- Database Access Layer
- Google Cloud Storage Integration

c) Data Layer:
- PostgreSQL Database (ElephantSQL)
- Google Cloud Storage Bucket
- External Data Sources (NHD streams/Urban Area datasets)

##### Component Relationships and Interactions

- Client → Backend: REST API calls (HTTP/HTTPS)
- Backend → Database: SQL queries via Psycopg2
- Backend → Google Cloud Storage: File storage/retrieval
- Backend → External Data Sources: Data integration
- Client → Mapbox API: Map visualization services

##### Detailed Component Breakdown

Frontend (React):
**[User Interface Layer]**
- Public Components
- Header
- Navigation
- Map Visualization
- Protected Components
- Upload Form
- Card Management
- Profile
- State Management
- API Integration

Backend (FastAPI):
**[API Layer]**
- Authentication Endpoints
- Card Management Endpoints
- File Management Endpoints
- Map Data Endpoints

**[Service Layer]**
- User Service
- Card Service
- File Service
- Map Service

**[Integration Layer]**
- Database Connector
- Google Cloud Storage
- External APIs

Database Schema:
**[PostgreSQL Tables]**
- Users
- Categories
- Cards
- Files
- Tags
- CardTags

##### Deployment Architecture

Deployment components:
- Netlify (Frontend hosting)
- Render.com (Backend hosting)
- ElephantSQL (Database hosting)
- Google Cloud Storage (File storage)

##### Security Layer

Security components:
- JWT Authentication
- Password Hashing
- API Security Middleware
- CORS Configuration

##### Additional Elements

Include:
- Version information
- Data flow indicators
- System boundaries
- External service integration points

Remember to emphasize:
- The separation between frontend and backend services
- The role of cloud services in the architecture
- Security implementation across layers
- Data flow patterns
- Integration points with external services

This will provide a clear understanding of the system's architecture while maintaining the necessary level of detail for implementation and maintenance.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        FE[React Application]:::frontend
        UI[User Interface Layer]:::frontend
        Auth[Authentication Module]:::auth
        Map[Map Visualization]:::frontend
        API[API Integration]:::frontend

        FE --> UI
        FE --> Auth
        FE --> Map
        FE --> API
        
        subgraph UI Components
            Header[Header]:::frontend
            Cards[Cards]:::frontend
            Forms[Forms]:::frontend
            
            UI --> Header
            UI --> Cards
            UI --> Forms
        end
    end

    subgraph Server
        BE[FastAPI Application]:::backend
        
        subgraph Controllers
            AC[Account Controller]:::backend
            CC[Card Controller]:::backend
            FC[File Controller]:::backend
            MC[Map Controller]:::backend
            
            BE --> AC
            BE --> CC
            BE --> FC
            BE --> MC
        end
        
        subgraph Services
            AuthS[Authentication Service]:::auth
            FileS[File Management Service]:::backend
            DBS[Database Access Layer]:::backend
            
            BE --> AuthS
            BE --> FileS
            BE --> DBS
        end
    end

    subgraph "Data Storage"
        DB[(PostgreSQL Database)]:::database
        GCS[("Google Cloud Storage")]:::external
        Files[("Local File Storage")]:::storage
    end

    subgraph "External Services"
        Mapbox[Mapbox API]:::external
        ExtData[External Datasets]:::external
    end

    %% Connections between major components
    API --> BE
    BE --> DB
    BE --> GCS
    BE --> Files
    Map --> Mapbox
    BE --> ExtData

    %% Click events for component mapping
    click FE "https://github.com/mitchellkolb/living-atlas/tree/main/client/src/"
    click Header "https://github.com/mitchellkolb/living-atlas/blob/main/client/src/Header.js"
    click Cards "https://github.com/mitchellkolb/living-atlas/blob/main/client/src/Card.js"
    click Forms "https://github.com/mitchellkolb/living-atlas/blob/main/client/src/FormModal.js"
    click Map "https://github.com/mitchellkolb/living-atlas/blob/main/client/src/PolygonBuilder.js"
    click Auth "https://github.com/mitchellkolb/living-atlas/blob/main/client/src/Login.js"
    click API "https://github.com/mitchellkolb/living-atlas/blob/main/client/src/api.js"
    click BE "https://github.com/mitchellkolb/living-atlas/tree/main/backend/"
    click AC "https://github.com/mitchellkolb/living-atlas/blob/main/backend/endpoint_files/account.py"
    click CC "https://github.com/mitchellkolb/living-atlas/blob/main/backend/endpoint_files/card.py"
    click FC "https://github.com/mitchellkolb/living-atlas/blob/main/backend/endpoint_files/cloudFile.py"
    click MC "https://github.com/mitchellkolb/living-atlas/blob/main/backend/endpoint_files/map.py"
    click DBS "https://github.com/mitchellkolb/living-atlas/blob/main/backend/database.py"
    click GCS "https://github.com/mitchellkolb/living-atlas/blob/main/backend/ServiceKey_GoogleCloud.json"
    click DB "https://github.com/mitchellkolb/living-atlas/blob/main/database/database_schema/livingAtlasTables.sql"
    click Files "https://github.com/mitchellkolb/living-atlas/tree/main/backend/app/savedFiles/"

    %% Styling
    classDef frontend fill:#2196F3,stroke:#fff,stroke-width:2px,color:#fff
    classDef backend fill:#4CAF50,stroke:#fff,stroke-width:2px,color:#fff
    classDef database fill:#FFC107,stroke:#fff,stroke-width:2px,color:#000
    classDef external fill:#9C27B0,stroke:#fff,stroke-width:2px,color:#fff
    classDef auth fill:#FF5722,stroke:#fff,stroke-width:2px,color:#fff
    classDef storage fill:#795548,stroke:#fff,stroke-width:2px,color:#fff
```
