# na1969na/bridge-app architecture

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

- Interactive diagram: https://gitdiagram.com/na1969na/bridge-app
- Repository: https://github.com/na1969na/bridge-app

## Overview

##### Project type and purpose
- This is a full-stack web application (“Bridge – Check-in App”) whose goal is to enable daily user check-ins, track them on a calendar, and notify emergency contacts (via SMS or email) if a check-in is missed for 72 hours.

##### File structure
- Top level separates “backend” and “frontend.”
- Backend follows an MVC-like pattern with
- src/controllers
- src/services
- src/repositories
- src/models
- src/middleware (JWT checks, error handling)
- src/config/db.ts for MongoDB connection
- Frontend is a React/Vite app in TypeScript with:
- src/api for HTTP clients (apiClient, checkInApi, userApi)
- src/components (UI, layout, modals, check-in widgets)
- src/hooks (data-fetching with TanStack Query)
- src/stores (Zustand for global state: user, check-in, toast, modal)
- src/pages (Home, About, UserSettings)
- src/schemas (Zod validation)
- Deployment/build files: package.json, tsconfig, vite.config.ts

##### Extract key insights from README
- Frontend: React, Zustand, TypeScript, TailwindCSS, Auth0 (JWT), React Hook Form + Zod, TanStack Query
- Backend: Node.js, Express.js, MongoDB
- External integrations: Auth0 for auth; an email/SMS service (e.g., Twilio or SendGrid)

##### Main components
a. Frontend Client
- Browser / React App (pages, components, Zustand stores, TanStack Query)
b. Authentication Service
- Auth0 (issues JWTs to the frontend; backend verifies JWT)
c. API Layer / Backend
- Express Server (server.ts → app.ts)
- Controllers (checkIn.controller, user.controller)
- Services (business logic)
- Repositories (data-access to MongoDB)
- Middleware (JWT validation, error handler)
d. Database
- MongoDB (collections: users, checkIns)
e. Notification Service
- External SMS/Email API (e.g., Twilio or SendGrid)

- Frontend → (1) Auth0 Login/Token Request
- Frontend (with JWT) → (2) API Requests → Backend Controllers
- Controllers → Services → Repositories → MongoDB
- Scheduled job or background task in Backend monitors check-in timestamps → (3) Notification Service
- Notification Service → Emergency Contacts (SMS or Email)

##### Architectural patterns and design principles
- Separation of concerns: Controllers vs. Services vs. Repositories
- API client abstraction on frontend (apiClient + typed endpoints)
- State management with Zustand + React Query for server state
- Schema validation with Zod at both ends
- JWT-based authentication via Auth0

- Internal layering of the backend (Controllers → Services → Repositories → DB)
- Data objects (User, CheckIn) next to the DB or repository
- Authentication flow: Auth0 ↔ Browser ↔ Backend (middleware)
- Technology choices (React, Express, MongoDB, Auth0, Twilio/SendGrid)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser["Browser / React App"]:::frontend
        Main["main.tsx"]:::frontend
        App["App.tsx"]:::frontend
        Pages["Pages<br/>Home.tsx, About.tsx, UserSettings.tsx"]:::frontend
        Components["Components"]:::frontend
        API["API Clients<br/>apiClient.ts, checkInApi.ts, userApi.ts"]:::frontend
        Hooks["Hooks<br/>checkIns.ts, users.ts"]:::frontend
        Stores["State Stores<br/>useCheckInStore.ts, useUserStore.ts, useModalStore.ts, useToastStore.ts"]:::frontend
        Schemas["Schemas<br/>userSchemas.ts"]:::frontend
    end

    %% Authentication Provider
    Auth0["Auth0 (JWT Issuer)"]:::external

    %% Backend/API Server
    subgraph "Backend/API Server"
        direction TB
        ServerTS["server.ts"]:::backend
        AppTS["app.ts"]:::backend
        Routes["Routes<br/>checkIn.routes.ts, user.routes.ts"]:::backend
        subgraph "Middleware"
            direction TB
            AuthMiddleware["checkJwt.ts, checkJwtSub.ts"]:::backend
            ErrorMiddleware["errorHandler.ts"]:::backend
        end
        subgraph "Controllers"
            direction TB
            CheckInController["checkIn.controller.ts"]:::backend
            UserController["user.controller.ts"]:::backend
        end
        subgraph "Services"
            direction TB
            CheckInService["checkIn.service.ts"]:::backend
            UserService["user.service.ts"]:::backend
        end
        subgraph "Repositories"
            direction TB
            CheckInRepo["checkInRepository.ts"]:::backend
            UserRepo["userRepository.ts"]:::backend
        end
        subgraph "Models"
            direction TB
            CheckInModel["checkIn.model.ts"]:::backend
            UserModel["user.model.ts"]:::backend
        end
        ConfigDB["db.ts"]:::backend
    end

    %% Database
    DB["MongoDB<br/>Collections: users, checkIns"]:::db

    %% Notification Service
    Notify["Notification Service<br/>(Twilio/SendGrid)"]:::external

    %% Flows
    Browser -->|"1. Login/Token Request"| Auth0
    Auth0 -->|"Token Response (JWT)"| Browser
    Browser -->|"2. API Request (with JWT)"| AppTS
    AppTS --> Routes
    Routes --> AuthMiddleware
    AuthMiddleware --> CheckInController
    AuthMiddleware --> UserController
    CheckInController --> CheckInService
    UserController --> UserService
    CheckInService --> CheckInRepo
    UserService --> UserRepo
    CheckInRepo --> DB
    UserRepo --> DB

    %% Background job for notifications
    CheckInService -.->|"Scheduled Check"| Notify
    Notify -->|"SMS/Email"| EmergencyContacts["Emergency Contacts"]:::external

    %% Click Events
    click Main "https://github.com/na1969na/bridge-app/blob/main/frontend/src/main.tsx"
    click App "https://github.com/na1969na/bridge-app/blob/main/frontend/src/App.tsx"
    click Pages "https://github.com/na1969na/bridge-app/tree/main/frontend/src/pages"
    click Components "https://github.com/na1969na/bridge-app/tree/main/frontend/src/components/"
    click API "https://github.com/na1969na/bridge-app/blob/main/frontend/src/api/apiClient.ts"
    click API "https://github.com/na1969na/bridge-app/blob/main/frontend/src/api/checkInApi.ts"
    click API "https://github.com/na1969na/bridge-app/blob/main/frontend/src/api/userApi.ts"
    click Hooks "https://github.com/na1969na/bridge-app/blob/main/frontend/src/hooks/checkIns.ts"
    click Hooks "https://github.com/na1969na/bridge-app/blob/main/frontend/src/hooks/users.ts"
    click Stores "https://github.com/na1969na/bridge-app/blob/main/frontend/src/stores/useCheckInStore.ts"
    click Stores "https://github.com/na1969na/bridge-app/blob/main/frontend/src/stores/useUserStore.ts"
    click Stores "https://github.com/na1969na/bridge-app/blob/main/frontend/src/stores/useModalStore.ts"
    click Stores "https://github.com/na1969na/bridge-app/blob/main/frontend/src/stores/useToastStore.ts"
    click Schemas "https://github.com/na1969na/bridge-app/blob/main/frontend/src/schemas/userSchemas.ts"

    click AuthMiddleware "https://github.com/na1969na/bridge-app/blob/main/backend/src/middleware/checkJwt.ts"
    click AuthMiddleware "https://github.com/na1969na/bridge-app/blob/main/backend/src/middleware/checkJwtSub.ts"
    click ErrorMiddleware "https://github.com/na1969na/bridge-app/blob/main/backend/src/middleware/errorHandler.ts"

    click ServerTS "https://github.com/na1969na/bridge-app/blob/main/backend/src/server.ts"
    click AppTS "https://github.com/na1969na/bridge-app/blob/main/backend/src/app.ts"
    click Routes "https://github.com/na1969na/bridge-app/blob/main/backend/src/routes/checkIn.routes.ts"
    click Routes "https://github.com/na1969na/bridge-app/blob/main/backend/src/routes/user.routes.ts"

    click CheckInController "https://github.com/na1969na/bridge-app/blob/main/backend/src/controllers/checkIn.controller.ts"
    click UserController "https://github.com/na1969na/bridge-app/blob/main/backend/src/controllers/user.controller.ts"

    click CheckInService "https://github.com/na1969na/bridge-app/blob/main/backend/src/services/checkIn.service.ts"
    click UserService "https://github.com/na1969na/bridge-app/blob/main/backend/src/services/user.service.ts"

    click CheckInRepo "https://github.com/na1969na/bridge-app/blob/main/backend/src/repositories/checkInRepository.ts"
    click UserRepo "https://github.com/na1969na/bridge-app/blob/main/backend/src/repositories/userRepository.ts"

    click CheckInModel "https://github.com/na1969na/bridge-app/blob/main/backend/src/models/checkIn.model.ts"
    click UserModel "https://github.com/na1969na/bridge-app/blob/main/backend/src/models/user.model.ts"

    click ConfigDB "https://github.com/na1969na/bridge-app/blob/main/backend/src/config/db.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#3399FF,stroke-width:1px
    classDef backend fill:#D0FFDA,stroke:#33CC33,stroke-width:1px
    classDef db fill:#FFE0B2,stroke:#FF9900,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#999999,stroke-width:1px,stroke-dasharray: 2 2
```
