# digitalaidseattle/culturous-exchange architecture

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

- Interactive diagram: https://gitdiagram.com/digitalaidseattle/culturous-exchange
- Repository: https://github.com/digitalaidseattle/culturous-exchange

## Overview

##### Project Type and Purpose
- This project is a line-of-business web application template (admin template) used for CRUD interfaces (e.g., inventory management, project/task tracking).
- According to the README, it provides common application shell features (toolbar, navbar, dialogs, form validation, drag-and-drop, Markdown support, etc.) and is built with React, TypeScript, Material UI, and Vite. It leverages Supabase for both authentication and RDBMS-backed data storage and is deployed as a static website on Firebase.

##### Analyzing the File Structure
- Top-level configuration files indicate use of environment variables (.env), deployment integration (firebase.json, .firebaserc, GitHub workflows), and project configuration (tsconfig.json, vite.config.ts).
- The source code is contained in the “src” directory which includes:
- UI components (src/components) and pages (src/pages). Pages are further grouped (e.g., cohorts, plan, students) reflecting separation of concerns (e.g., cohort management, student management).
- API calls are abstracted in the “src/api” folder – suggesting a service layer that interacts with Supabase.
- Assets and styles are organized to support the visual interface.
- The “supabase” folder includes migration SQL files and configuration, clearly showing integration with Supabase for database schema management.
- Deployment scripts and GitHub actions (Firebase and Supabase workflows) indicate an automated CI/CD pipeline for hosting.

a. Frontend (User Interface)
- React Application (built with Vite & TypeScript)
- UI Components & Pages (e.g., App.tsx, pages such as cohorts, plan, students)
- Assets including images, CSS styling, and third-party libraries (e.g., react-map-gl for maps, @dnd-kit for drag-and-drop, react-markdown for Markdown)

b. API / Service Layer
- API Clients in “src/api” (e.g., ceCohortService, ceStudentService, etc.) which encapsulate calls to back-end services.
- Service hooks (e.g., useAppConstants) in “src/services”

c. Backend Services and Data Storage (Supabase)
- Supabase Authentication & Authorization (implementation for Google and Microsoft)
- CRUD operations using Supabase RDBMS
- File Storage via Supabase’s storage system

d. Deployment and CI/CD
- Firebase web hosting configuration (firebase.json, .firebaserc, and related workflows)
- GitHub Actions for deployment and environment management (workflows for Firebase and Supabase)

e. Additional Modules/Features:
- Maps (using react-map-gl and maplibre-gl)
- Drag & Drop features (@dnd-kit/core, @dnd-kit/sortable)
- Markdown rendering (react-markdown)

##### Relationships and Data Flow
- The web client (React Application) is the entry point for users.
- UI components make use of API services that communicate with Supabase for fetching and updating data (CRUD operations, authentication, file storage).
- Authentication flows utilize Supabase’s endpoints, with the clients using environment configuration (.env files) to connect.
- Deployment flows are managed via GitHub actions which trigger Firebase hosting updates after the build.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Differentiation between presentation (React components and pages), business logic (API layer), and data (Supabase).
- Modular Design: Organized file structure (pages, components, api) encourages reusability and maintainability.
- Clear use of external integrations (Supabase for DB and auth, Firebase for deployment, third-party libraries for UI enhancements).

## Diagram (Mermaid)

```mermaid
flowchart TD
    U1["User Browser"]:::external

    subgraph "React Frontend (Vite + TypeScript)"
        FE1["Application Shell (src/App.tsx)"]:::frontend
        FE2["Main Entry (src/main.tsx)"]:::frontend
        FE3["UI Components (src/components)"]:::frontend
        FE4["Pages (src/pages)"]:::frontend
        FE5["Assets & Styling (src/assets, CSS)"]:::frontend
        FE6["Third-Party Libraries (Maps,Drag&Drop,Markdown)"]:::frontend
    end

    subgraph "API/Service Layer"
        API1["ceCohortService.ts (src/api)"]:::api
        API2["ceEnrollmentService.ts (src/api)"]:::api
        API3["cePlanService.ts (src/api)"]:::api
        API4["ceStudentService.ts (src/api)"]:::api
        API5["entityService.ts (src/api)"]:::api
        API6["types.ts (src/api)"]:::api
        API7["useAppConstants.tsx (src/services)"]:::api
    end

    subgraph "Supabase Backend"
        SB1["Supabase DB & File Storage (Auth,CRUD)"]:::backend
        SB2["Config & Migrations (supabase/config.toml & migrations)"]:::backend
    end

    subgraph "Deployment & CI/CD"
        DEP1["Firebase Hosting (firebase.json, .firebaserc)"]:::deployment
        DEP2["GitHub Actions (github/workflows)"]:::deployment
        DEP3["Environment Config (.env)"]:::deployment
    end

    U1 --> FE1
    FE3 -->|"calls"| API1
    API7 -->|"communicates"| SB1
    SB2 -->|"schema_update"| SB1
    DEP2 -->|"deploys"| DEP1

    %% Click Events for React Frontend
    click FE1 "https://github.com/digitalaidseattle/culturous-exchange/blob/main/src/App.tsx"
    click FE2 "https://github.com/digitalaidseattle/culturous-exchange/blob/main/src/main.tsx"
    click FE3 "https://github.com/digitalaidseattle/culturous-exchange/tree/main/src/components"
    click FE4 "https://github.com/digitalaidseattle/culturous-exchange/tree/main/src/pages"
    click FE5 "https://github.com/digitalaidseattle/culturous-exchange/tree/main/src/assets"
    click FE6 "https://github.com/digitalaidseattle/culturous-exchange/tree/main/src/assets/third-party"

    %% Click Events for API/Service Layer
    click API1 "https://github.com/digitalaidseattle/culturous-exchange/blob/main/src/api/ceCohortService.ts"
    click API2 "https://github.com/digitalaidseattle/culturous-exchange/blob/main/src/api/ceEnrollmentService.ts"
    click API3 "https://github.com/digitalaidseattle/culturous-exchange/blob/main/src/api/cePlanService.ts"
    click API4 "https://github.com/digitalaidseattle/culturous-exchange/blob/main/src/api/ceStudentService.ts"
    click API5 "https://github.com/digitalaidseattle/culturous-exchange/blob/main/src/api/entityService.ts"
    click API6 "https://github.com/digitalaidseattle/culturous-exchange/blob/main/src/api/types.ts"
    click API7 "https://github.com/digitalaidseattle/culturous-exchange/blob/main/src/services/useAppConstants.tsx"

    %% Click Events for Supabase Backend
    click SB1 "https://github.com/digitalaidseattle/culturous-exchange/tree/main/supabase"
    click SB2 "https://github.com/digitalaidseattle/culturous-exchange/blob/main/supabase/config.toml"

    %% Click Events for Deployment & CI/CD
    click DEP1 "https://github.com/digitalaidseattle/culturous-exchange/blob/main/firebase.json"
    click DEP2 "https://github.com/digitalaidseattle/culturous-exchange/tree/main/.github/workflows"
    click DEP3 "https://github.com/digitalaidseattle/culturous-exchange/blob/main/.env"

    %% Styles
    classDef frontend fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef api fill:#AED6F1,stroke:#3498DB,stroke-width:2px;
    classDef backend fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef deployment fill:#F5CBA7,stroke:#E59866,stroke-width:2px;
    classDef external fill:#D7DBDD,stroke:#566573,stroke-width:2px,color:#000;
```
