# ualberta-cmput401/f24project-bleeding-heart-art-space architecture

> Architecture diagram of the GitHub repository ualberta-cmput401/f24project-bleeding-heart-art-space, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ualberta-cmput401/f24project-bleeding-heart-art-space
- Repository: https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space

## Overview

##### Project Type and Purpose
- This is a full‐stack web application (“Volunteer Management Platform”) comprising:
- A React/TypeScript single‐page application (SPA) frontend
- A Node.js/Express/TypeScript monolithic backend API
- A PostgreSQL relational database
- Integrations with external services (email provider, Firebase SDK)
- Docker/Docker‐Compose orchestration and CI pipelines

##### File Structure
- Top‐level directories “frontend” and “backend” indicate two containers/services.
- “backend/src” is organized feature‑by‑feature (controllers, services, models, routes), revealing an MVC‑style pattern.
- “common” folders contain shared config, middleware, utils, and migrations (PostgreSQL schema managed with timestamped migration files).
- “frontend/src” is organized into pages, components, hooks, context, stores, and utilities—typical React SPA with state management via custom hooks and global context.
- Dockerfile and docker-compose.yml orchestrate containers (frontend, backend, database).
- GitHub Actions workflow for running backend tests indicates a CI pipeline.

##### README Insights
- Confirms high‑level overview: React + Node + TypeScript + PostgreSQL + Firebase.
- Features: event/shift creation, volunteer signup, calendar view, artist requests, email notifications, attendance tracking.
- Development: separate “npm run dev” for frontend and backend; acceptance tests under “tests” folder use Mocha.

a. Main Containers/Components
- User’s Web Browser (client device)
- Nginx (static host for the SPA) or direct Vite dev server in dev mode
- React SPA frontend (pages, components, context, state stores)
- Node/Express backend API (app.ts → server.ts)
- PostgreSQL Database (hosted in Docker)
- External Email Service (e.g., SendGrid via SMTP or other API)
- Firebase (authentication, push notifications)
- CI/CD Runner (GitHub Actions)

b. Relationships and Data Flows
- Browser → (HTTP/HTTPS) → Nginx/SPA → (AJAX/Fetch) → Backend API
- Backend → (SQL) → PostgreSQL (queries, migrations)
- Backend → (SMTP/API) → Email Service
- Frontend → (Firebase SDK) → Firebase Auth/Realtime services
- CI Pipeline → (runs) → Backend Tests → Report status to GitHub

c. Architectural Patterns & Design Principles
- Monolithic backend using MVC/feature modules.
- RESTful API layer with controllers → services → models.
- Feature‐based folder layout to isolate domain logic (events, users, shifts, notifications).
- React Context and custom hooks for state management on the frontend.
- Environment‐based configuration (dotenv in backend, .env in frontend).
- Containerization: each major component runs in its own Docker container.
- Migration‐first database schema management.

d. Key Technologies
- Frontend: React, TypeScript, Vite, Tailwind/CSS Modules, React Router
- Backend: Node.js, Express, TypeScript, Jest (unit tests), Umzug/TypeORM/knex‐like migrations
- Database: PostgreSQL
- External: Firebase SDK, Email provider
- DevOps: Docker, docker-compose, GitHub Actions

- Controllers (handle routes)
- Services (business logic)
- Models (database schemas)
- Middlewares (auth, logging)
- Config & Utils
- Pages (Account, Calendar, EventDetails, etc.)
- Shared Components (Layout, Dialogs, Snackbar)
- State Stores & Context Providers
- Utility modules (fetch wrappers, auth helper)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client"
        Browser["Web Browser"]:::external
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        Nginx["Nginx / Vite Dev Server"]:::frontend
        SPA["React/TypeScript SPA"]:::frontend
    end

    %% SPA Internal Structure
    subgraph "SPA Components"
        Entry["main.tsx"]:::frontend
        App["App.tsx & AppLayout.tsx"]:::frontend
        Router["router.tsx"]:::frontend
        Pages["pages"]:::frontend
        Components["components"]:::frontend
        State["context & stores"]:::frontend
        Utils["utils"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        API["Node.js/Express API"]:::backend
    end

    %% API Internal Structure
    subgraph "API Components"
        Appts["app.ts & server.ts"]:::backend
        Features["features"]:::backend
        CommonCfg["common/config & middlewares"]:::backend
        DBConn["database.ts & migrations"]:::backend
        SendEmails["sendEmails feature"]:::backend
    end

    %% Database
    DB["PostgreSQL"]:::db

    %% External Services
    subgraph "External Services"
        Email["Email Service"]:::external
        Firebase["Firebase"]:::external
    end

    %% CI/CD
    CI["GitHub Actions CI"]:::ci

    %% Connections
    Browser -->|"HTTP/HTTPS"| Nginx
    Nginx --> SPA
    SPA -->|"HTTP REST"| API
    SPA -->|"Firebase Auth SDK"| Firebase
    API -->|"SQL queries"| DB
    API -->|"SMTP/API calls"| Email
    CI -->|"runs tests"| API

    %% Internal Connections SPA
    SPA --> Entry
    SPA --> App
    SPA --> Router
    SPA --> Pages
    SPA --> Components
    SPA --> State
    SPA --> Utils

    %% Internal Connections API
    API --> Appts
    API --> Features
    API --> CommonCfg
    API --> DBConn
    API --> SendEmails

    %% Click Events
    click SPA "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/tree/main/frontend/src"
    click Entry "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/blob/main/frontend/src/main.tsx"
    click App "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/blob/main/frontend/src/app/App.tsx"
    click App "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/blob/main/frontend/src/app/AppLayout.tsx"
    click Router "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/blob/main/frontend/src/router.tsx"
    click Pages "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/tree/main/frontend/src/app/pages"
    click Components "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/tree/main/frontend/src/components"
    click State "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/tree/main/frontend/src/lib/context"
    click State "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/tree/main/frontend/src/stores"
    click Utils "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/tree/main/frontend/src/utils"
    click API "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/blob/main/backend/src/app.ts"
    click API "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/blob/main/backend/src/server.ts"
    click Features "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/tree/main/backend/src/features"
    click CommonCfg "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/tree/main/backend/src/common/config"
    click CommonCfg "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/tree/main/backend/src/common/middlewares"
    click DBConn "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/blob/main/backend/src/common/database/database.ts"
    click DBConn "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/tree/main/backend/src/common/database/migrations"
    click SendEmails "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/tree/main/backend/src/features/sendEmails"
    click Firebase "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/blob/main/frontend/src/utils/firebase.ts"
    click CI "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/blob/main/.github/workflows/backend-tests.yml"
    click Dockerfile "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/tree/main/Dockerfile"
    click Dockerfile "https://github.com/ualberta-cmput401/f24project-bleeding-heart-art-space/blob/main/docker-compose.yml"

    %% Classes
    classDef frontend fill:#e6ffe6,stroke:#2ecc71,color:#145A32
    classDef backend fill:#e6f2ff,stroke:#3498db,color:#1A5276
    classDef db fill:#fff4e6,stroke:#e67e22,color:#A04000
    classDef external fill:#f2f2f2,stroke:#95a5a6,color:#566573
    classDef ci fill:#f5e6ff,stroke:#9b59b6,color:#4A235A
```
