# yogeshp-code/heartbeat architecture

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

- Interactive diagram: https://gitdiagram.com/yogeshp-code/heartbeat
- Repository: https://github.com/yogeshp-code/heartbeat

## Overview

##### Project type and purpose
- This is a monorepo housing a full-stack web application called Heartbeat Portal.
- Purpose: Provide a unified, low-cost dashboard that displays real-time ECS cluster and service metrics across AWS environments.
- Frontend: Next.js + React for UI/UX.
- Backend: FastAPI for REST API endpoints, AWS ECS data retrieval, and JWT-based authentication.

##### File structure
Top-level
├── backend/           ← FastAPI service
│     ├ Dockerfile
│     ├ main.py        ← App entrypoint
│     ├ auth/          ← Authentication module (models, encryption, JWT, database)
│     ├ routes.py      ← API route definitions
│     └ requirements.txt
├── frontend/          ← Next.js application
│     ├ Dockerfile
│     ├ app/           ← Next.js App Router pages (login, layout, loading)
│     ├ components/    ← Shared UI library components and theme provider
│     ├ src/           ← React components, contexts (AuthContext), API client, types
│     ├ hooks/         ← Custom React hooks (useMobile, useToast)
│     ├ public/, styles/, config files
│     └ package.json
├── images/
└── readme.md

##### Extract insights from README
- Monorepo with two subsystems (backend/front).
- Backend authenticates users (JWT) and calls AWS ECS APIs to fetch cluster/service data.
- Frontend consumes backend API, handles login flow, stores JWT, and renders dashboard components.
- Containerized via Docker for portability.

##### Detail without overthinking
- Decompose each major subsystem into sub-components (Auth, Routes, ECS Client, UI Components, Context).
- Data flow from User → Frontend → Backend → AWS and back.
- Where JWT is generated, stored, and validated.
- Containerization as a deployment concern.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["User (Browser)"]:::user

    %% Frontend Container
    subgraph "Frontend Container (Docker)" 
        direction TB
        UI_Layer["UI Layer (Next.js App Router)"]:::frontend
        Shared_UI["Shared UI Components Library"]:::frontend
        Theme["Theme Provider"]:::frontend
        Entry["Application Entry (main.tsx)"]:::frontend
        AuthCtx["Auth Context (JWT Storage)"]:::frontend
        APIClient["API Client (HTTP Wrapper)"]:::frontend
        MobileHook["useMobile Hook"]:::frontend
        ToastHook["useToast Hook"]:::frontend
        Dashboard["Dashboard Components"]:::frontend
        Styles["Global Styles & Config"]:::frontend
        FDocker["Dockerfile"]:::frontend
    end

    %% Backend Container
    subgraph "Backend Container (Docker)" 
        direction TB
        BE_Main["FastAPI Entrypoint"]:::backend
        BE_Routes["API Route Definitions"]:::backend
        subgraph "Auth Module"
            direction TB
            AuthModels["Auth Models"]:::backend
            AuthDB["Database Setup"]:::backend
            AuthEnc["Password Encryption"]:::backend
            AuthJWT["JWT Handling"]:::backend
            AuthDeps["Dependency Injection"]:::backend
            AuthRoutes["Auth Routes (login/signup)"]:::backend
        end
        ECSClient["ECS Service Client"]:::backend
        BDocker["Dockerfile"]:::backend
        Requirements["requirements.txt"]:::backend
    end

    %% AWS ECS External
    AWS_ECS["AWS ECS API"]:::external

    %% Flows
    User -->|"HTTP(S) load"| UI_Layer
    UI_Layer -->|"renders pages"| Shared_UI
    UI_Layer -->|"uses theme"| Theme
    UI_Layer -->|"mounts app"| Entry
    UI_Layer -->|"wraps with"| AuthCtx
    AuthCtx -->|"calls"| APIClient
    APIClient -->|"GET/POST Requests"| BE_Routes
    APIClient -->|"attaches JWT"| BE_Routes
    MobileHook --> UI_Layer
    ToastHook --> UI_Layer
    Dashboard --> UI_Layer
    Styles --> UI_Layer
    FDocker --> UI_Layer

    BE_Main --> BE_Routes
    BE_Routes --> AuthRoutes
    AuthRoutes --> AuthModels
    AuthRoutes --> AuthDB
    AuthRoutes --> AuthEnc
    AuthRoutes --> AuthJWT
    AuthRoutes --> AuthDeps
    BE_Routes --> ECSClient
    ECSClient --> AWS_ECS
    BDocker --> BE_Main
    Requirements --> BE_Main

    %% Click Events - Frontend
    click UI_Layer "https://github.com/yogeshp-code/heartbeat/tree/main/frontend/app"
    click Shared_UI "https://github.com/yogeshp-code/heartbeat/tree/main/frontend/components/ui"
    click Theme "https://github.com/yogeshp-code/heartbeat/blob/main/frontend/components/theme-provider.tsx"
    click MobileHook "https://github.com/yogeshp-code/heartbeat/blob/main/frontend/hooks/use-mobile.tsx"
    click ToastHook "https://github.com/yogeshp-code/heartbeat/blob/main/frontend/hooks/use-toast.ts"
    click AuthCtx "https://github.com/yogeshp-code/heartbeat/blob/main/frontend/src/contexts/AuthContext.tsx"
    click APIClient "https://github.com/yogeshp-code/heartbeat/blob/main/frontend/src/api.ts"
    click Entry "https://github.com/yogeshp-code/heartbeat/blob/main/frontend/src/main.tsx"
    click Dashboard "https://github.com/yogeshp-code/heartbeat/tree/main/frontend/src/components"
    click Styles "https://github.com/yogeshp-code/heartbeat/blob/main/frontend/styles/globals.css"
    click Styles "https://github.com/yogeshp-code/heartbeat/blob/main/frontend/tailwind.config.js"
    click FDocker "https://github.com/yogeshp-code/heartbeat/tree/main/frontend/Dockerfile"

    %% Click Events - Backend
    click BE_Main "https://github.com/yogeshp-code/heartbeat/blob/main/backend/main.py"
    click BE_Routes "https://github.com/yogeshp-code/heartbeat/blob/main/backend/routes.py"
    click AuthModels "https://github.com/yogeshp-code/heartbeat/blob/main/backend/auth/models.py"
    click AuthDB "https://github.com/yogeshp-code/heartbeat/blob/main/backend/auth/database.py"
    click AuthEnc "https://github.com/yogeshp-code/heartbeat/blob/main/backend/auth/encryption.py"
    click AuthJWT "https://github.com/yogeshp-code/heartbeat/blob/main/backend/auth/jwt_handler.py"
    click AuthDeps "https://github.com/yogeshp-code/heartbeat/blob/main/backend/auth/dependencies.py"
    click AuthRoutes "https://github.com/yogeshp-code/heartbeat/blob/main/backend/auth/routes.py"
    click ECSClient "https://github.com/yogeshp-code/heartbeat/blob/main/backend/routes.py"
    click BDocker "https://github.com/yogeshp-code/heartbeat/tree/main/backend/Dockerfile"
    click Requirements "https://github.com/yogeshp-code/heartbeat/blob/main/backend/requirements.txt"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#3399ff,color:#003366;
    classDef backend fill:#d4edda,stroke:#28a745,color:#155724;
    classDef external fill:#fff3cd,stroke:#ffcd39,color:#856404;
    classDef user fill:#e2e3e5,stroke:#6c757d,color:#1b1e21;
```
