# savire/ebuddy architecture

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

- Interactive diagram: https://gitdiagram.com/savire/ebuddy
- Repository: https://github.com/savire/ebuddy

## Overview

##### Project type and purpose
- This is a full-stack mono-repo managed by TurboRepo.
- It contains:
- a Next.js-based React frontend (/apps/frontend-repo)
- a Node/Express-style backend API with Firebase Cloud Functions support (/apps/backend-repo)
- a shared TypeScript package for common entities (/packages/shared)
- Its purpose is to showcase a simple “eBuddy” app using Firebase Auth & Firestore, running locally via the Firebase emulator.

##### File structure
- Top-level mono-repo:
- turbo.json – orchestrates parallel dev and emu scripts
- package.json – root scripts: `turbo run dev` / `turbo run emu`
- /packages/shared:
- entities/user.ts – shared domain model
- /apps/frontend-repo:
- Next.js “app router” under /app (layout.tsx, page.tsx, login/, member/)
- /apis/auth.js – client calls to Firebase Auth
- /store – Redux-style slice and store
- /components – UI dialogs, toasts, member action buttons
- /apps/backend-repo:
- config/firebaseAdmin.ts – initializes Firebase Admin SDK
- core/app.ts – configures Express app, middleware
- routes/userRoutes.ts + controller/api.ts – HTTP endpoints (REST)
- repository/userCollection.ts – data layer wrapping Firestore
- middleware/authMiddleware.ts – secures endpoints
- /functions – Firebase Cloud Functions definitions & emulator export data

##### README insights
- Dev commands:
- `npm run dev` – starts individual app
- `npm run emu` – starts Firebase emulator for functions
- `turbo run dev|emu` – runs both frontend & backend in parallel
- Emphasizes local Firebase emulation, requiring client auth config in /apps/frontend-repo/apis/auth.js

##### Detailed capture of architectural elements
- Don’t just show “frontend → backend.” Drill down to:
- Next.js App Router
- API layer in /apps/backend-repo/core/app.ts
- Middleware/auth
- Repository/firestore calls
- Cloud Functions folder for special tasks (data export)
- How the Firebase emulator suite connects to both functions and the Next.js client.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer and Tooling
    Dev["Developer \n(npm/turbo scripts)"]:::developer
    Dev -->|runs dev/emu| MonoRepo

    %% Mono-repo Coordination
    MonoRepo["TurboRepo Mono-repo"]:::developer
    MonoRepo --> Shared
    MonoRepo --> FrontendApp
    MonoRepo --> BackendApp

    %% Shared Entities
    subgraph "Shared Package" 
        direction TB
        SharedIndex["index.ts"]:::code
        UserEntity["entities/user.ts"]:::code
    end
    SharedIndex --> UserEntity

    %% Frontend Application
    subgraph "Next.js Frontend" 
        direction TB
        NextApp["App Router\n(layout.tsx, page.tsx, login/, member/)"]:::code
        AuthAPI["apis/auth.js"]:::code
        Store["store\n(pageSlice.ts, store.ts)"]:::code
        Components["components\n(Dialogs, Toasts, ActionButtons.tsx)"]:::code
        Theme["theme\nThemeWrapper.tsx"]:::code
    end

    %% Backend API and Functions
    subgraph "Backend API & Functions"
        direction TB
        subgraph "Express API"
            direction TB
            ExpressApp["core/app.ts"]:::code
            FirebaseAdmin["config/firebaseAdmin.ts"]:::code
            Routes["routes/userRoutes.ts"]:::code
            Controller["controller/api.ts"]:::code
            Middleware["middleware/authMiddleware.ts"]:::code
            Repository["repository/userCollection.ts"]:::code
        end
        subgraph "Firebase Cloud Functions"
            direction TB
            FunctionsEntry["functions/src/index.ts"]:::code
            ExportData["functions/export-data/"]:::code
        end
    end

    %% External Services & Emulator
    subgraph "Local Firebase Emulator Suite" 
        direction TB
        Emulator["Emulator (Auth, Firestore)"]:::runtime
    end
    subgraph "Firebase Services\n(Prod)" 
        direction TB
        Auth["Auth"]:::external
        Firestore["Firestore"]:::external
    end

    %% Relationships
    MonoRepo --> SharedIndex
    SharedIndex --> NextApp
    SharedIndex --> ExpressApp

    NextApp -->|REST/API calls| ExpressApp
    NextApp -->|Auth SDK| Emulator
    ExpressApp -->|Admin SDK| Emulator

    Emulator --> Auth
    Emulator --> Firestore

    ExpressApp --> Middleware
    Middleware --> Controller
    Controller --> Repository
    Repository --> Emulator

    ExpressApp --> FirebaseAdmin

    ExpressApp --> Routes

    FunctionsEntry -->|uses Admin SDK| Emulator
    ExportData -->|emulator export| Emulator

    %% Connection from Cloud Functions to Emulator
    Emulator --> FunctionsEntry

    %% Click Events
    click MonoRepo "https://github.com/savire/ebuddy/blob/main/turbo.json"
    click MonoRepo "https://github.com/savire/ebuddy/blob/main/package.json"
    click SharedIndex "https://github.com/savire/ebuddy/blob/main/packages/shared/index.ts"
    click UserEntity "https://github.com/savire/ebuddy/blob/main/packages/shared/entities/user.ts"
    click NextApp "https://github.com/savire/ebuddy/tree/main/apps/frontend-repo/app/"
    click AuthAPI "https://github.com/savire/ebuddy/blob/main/apps/frontend-repo/apis/auth.js"
    click Store "https://github.com/savire/ebuddy/tree/main/apps/frontend-repo/store/"
    click Components "https://github.com/savire/ebuddy/tree/main/apps/frontend-repo/components/"
    click Theme "https://github.com/savire/ebuddy/blob/main/apps/frontend-repo/theme/ThemeWrapper.tsx"
    click ExpressApp "https://github.com/savire/ebuddy/blob/main/apps/backend-repo/core/app.ts"
    click FirebaseAdmin "https://github.com/savire/ebuddy/blob/main/apps/backend-repo/config/firebaseAdmin.ts"
    click Routes "https://github.com/savire/ebuddy/blob/main/apps/backend-repo/routes/userRoutes.ts"
    click Controller "https://github.com/savire/ebuddy/blob/main/apps/backend-repo/controller/api.ts"
    click Middleware "https://github.com/savire/ebuddy/blob/main/apps/backend-repo/middleware/authMiddleware.ts"
    click Repository "https://github.com/savire/ebuddy/blob/main/apps/backend-repo/repository/userCollection.ts"
    click FunctionsEntry "https://github.com/savire/ebuddy/blob/main/apps/backend-repo/functions/src/index.ts"
    click ExportData "https://github.com/savire/ebuddy/tree/main/apps/backend-repo/functions/export-data/"

    %% Styles
    classDef developer fill:#DDDDDD,stroke:#333,stroke-width:1px;
    classDef code fill:#BBEEFF,stroke:#333,stroke-width:1px;
    classDef runtime fill:#CCFFCC,stroke:#333,stroke-width:1px;
    classDef external fill:#FFDD99,stroke:#333,stroke-width:1px;
```
