# greengeneers/emeraldchip architecture

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

- Interactive diagram: https://gitdiagram.com/greengeneers/emeraldchip
- Repository: https://github.com/greengeneers/emeraldchip

## Overview

##### Project Type and Purpose
- This is a full-stack web application with a React frontend and an Express/Node backend, persisting data in a PostgreSQL database via Knex.
- From the README: user auth, dashboards, events, donations, and RSVPs are core features.

##### File Structure
- Top-level:
- frontend/ – React SPA (Vite-powered)
- server/ – Express API server
- frontend/src structure follows a component- and adapter-driven pattern:
- adapters – encapsulate all HTTP calls to backend endpoints
- contexts – global state (current user)
- components/pages – UI building blocks and routes
- server/ structure follows MVC-like organization:
- controllers – HTTP request handlers
- models – ORM wrappers (Knex Query Builders)
- db/ – Knex configuration, migrations, seeds
- middleware – sessions, auth checks, logging
- Config & build scripts:
- vite.config.js, package.json (frontend)
- knexfile.js, .env.template (server)

##### README for Additional Insights
- Stack: Node, Express, PostgreSQL, React, Knex.
- Auth uses cookie-based sessions encrypted with SESSION_SECRET.
- Build flow: frontend build → server migrations/seeds → start server.

a. Main Components
- Client (Browser/React SPA)
- API Server (Express)
- Database (PostgreSQL via Knex)
- External/Dev Tools (Vite, Knex migrations, seeds)
b. Relationships & Data Flows
1. User interacts with React UI (components/pages).
2. Components call adapters → fetch/POST JSON to Express endpoints.
3. Express routes → middleware (session, auth) → controllers.
4. Controllers invoke models (Knex) → SQL queries to Postgres.
5. Responses bubble back: DB → model → controller → adapter → UI.
c. Architectural Patterns
- Layered Architecture (Presentation → API → Data)
- Adapter pattern in frontend to decouple UI from HTTP details
- MVC-style on server (controllers + models)
- Cookie-based session management middleware
d. Key Technologies & Frameworks
- React + Vite (frontend build/server)
- Express + cookie-session (server)
- Knex + PostgreSQL (database)
- ESLint / Airbnb style guide

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (React SPA)" 
        direction TB
        Browser["User / Browser"]:::ui
        App["App.jsx"]:::ui
        Pages["Page Routes"]:::ui
        UIComps["UI Components"]:::ui
        Contexts["Global State Context"]:::ui
        Adapters["HTTP Adapters"]:::ui

        Browser -->|"open app"| App
        App -->|"renders routes"| Pages
        App -->|"uses components"| UIComps
        App -->|"provides context"| Contexts
        App -->|"calls API via"| Adapters
    end

    %% Backend Layer
    subgraph "Backend (Express API)" 
        direction TB
        Middleware["Middleware\n(cookieSessions, auth, logging)"]:::server
        Controllers["Controllers"]:::server
        Models["Models (Knex)"]:::server

        Adapters -->|"HTTP GET/POST /api/*"| Middleware
        Middleware -->|"authenticate & route"| Controllers
        Controllers -->|"invoke knex queries"| Models
    end

    %% Database Layer
    subgraph "Database (PostgreSQL)" 
        direction TB
        DB["PostgreSQL"]:::db
        Migrations["Migrations"]:::db
        Seeds["Seed Data"]:::db

        Models -->|"SQL Queries"| DB
        DB -->|"return rows"| Models
    end

    %% Dev Tools
    subgraph "Dev & Build Tools" 
        direction TB
        Vite["Vite Build"]:::tool
        KnexCLI["Knex Migrate/Seed"]:::tool

        Vite -->|"build frontend"| App
        KnexCLI -->|"run migrations"| Migrations
        KnexCLI -->|"run seeds"| Seeds
    end

    %% Click Events
    click App "https://github.com/greengeneers/emeraldchip/blob/main/frontend/src/App.jsx"
    click Adapters "https://github.com/greengeneers/emeraldchip/tree/main/frontend/src/adapters"
    click Contexts "https://github.com/greengeneers/emeraldchip/tree/main/frontend/src/contexts"
    click UIComps "https://github.com/greengeneers/emeraldchip/tree/main/frontend/src/components"
    click Pages "https://github.com/greengeneers/emeraldchip/tree/main/frontend/src/pages"
    click Vite "https://github.com/greengeneers/emeraldchip/blob/main/frontend/vite.config.js"
    click Middleware "https://github.com/greengeneers/emeraldchip/tree/main/server/middleware"
    click Controllers "https://github.com/greengeneers/emeraldchip/tree/main/server/controllers"
    click Models "https://github.com/greengeneers/emeraldchip/tree/main/server/models"
    click DB "https://github.com/greengeneers/emeraldchip/tree/main/server/db"
    click Migrations "https://github.com/greengeneers/emeraldchip/blob/main/server/db/migrations/20250430130305_init.js"
    click Seeds "https://github.com/greengeneers/emeraldchip/blob/main/server/db/seeds/init.js"
    click KnexCLI "https://github.com/greengeneers/emeraldchip/blob/main/knexfile.js"

    %% Styles
    classDef ui fill:#E8F4FC,stroke:#0288D1,stroke-width:1px
    classDef server fill:#F1F8E9,stroke:#7CB342,stroke-width:1px
    classDef db fill:#FFF3E0,stroke:#FB8C00,stroke-width:1px
    classDef tool fill:#F3E5F5,stroke:#8E24AA,stroke-width:1px
```
