# geekyroshan/streak-webapp architecture

> Architecture diagram of the GitHub repository geekyroshan/streak-webapp, 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/geekyroshan/streak-webapp
- Repository: https://github.com/geekyroshan/streak-webapp

## Overview

##### Project type and purpose
- This is a full-stack web application called **GitHub Streak Manager**. Its purpose is to present a React-powered UI for viewing and fixing GitHub contribution streaks and to provide a REST API backend for data storage, authentication, and business logic.

##### File structure
- **Root folder**
- index.html, public/ → static assets for the React SPA
- main.py (unused or auxiliary script)
- package.json, bun.lockb, setup.sh, restart-servers.sh → build/install scripts
- .env.example, server/.env.example → environment variable templates
- **server/** (Express + TypeScript)
- src/config → DB and GitHub OAuth configuration
- src/controllers → route handlers (auth, repo, contribution, streak, user, GitHub callbacks)
- src/routes → express.Router definitions mapping endpoints to controllers
- src/middleware → auth and error-handling middleware
- src/models → MongoDB schemas (user, commit)
- src/services → GitHub API client, in-memory MongoDB server (for testing), scheduler service
- src/utils → error class and time utilities
- **src/** (React + TypeScript + Vite)
- src/pages → top-level page components (Dashboard, ActivityPage, Settings, etc.)
- src/components → reusable UI pieces (ActivityCalendar, GapAnalysis, Sidebar, BackdatingCard, plus shadcn/ui primitives)
- src/hooks → data fetching and state hooks (use-commit-history, use-github-profile, etc.)
- src/lib → global contexts and API wrapper (AuthContext, api.ts)
- index.css, App.tsx, main.tsx, tailwind.config.ts, vite.config.ts → styling and build setup

##### README for additional insights
- It confirms a React+Vite frontend, Express+TypeScript backend, MongoDB persistence, and GitHub OAuth.

##### Essential architectural elements
- Don’t omit the scheduler.service.ts background job layer.
- How temp files (server/temp) are used during bulk backdating.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser)" 
        direction TB
        SPA["React SPA"]:::frontend
        Entry["index.html"]:::frontend
        Init["main.tsx"]:::frontend
        Root["App.tsx"]:::frontend
        Pages["Pages (src/pages/)"]:::frontend
        Components["UI Components (src/components/)"]:::frontend
        Hooks["Hooks (src/hooks/)"]:::frontend
        Lib["Global Contexts & API (src/lib/)"]:::frontend
        ConfigFE["Build & Config"]:::frontend
        Assets["Static Assets (public/)"]:::frontend
    end

    %% Server Layer
    subgraph "API Server (Express + TS)" 
        direction TB
        ServerEntry["server/src/index.ts"]:::backend
        subgraph "Configuration"
            DBConfig["database.ts"]:::backend
            OAuthConfig["github.ts"]:::backend
        end
        subgraph "Routes"
            AuthRoutes["auth.routes.ts"]:::backend
            ContributionRoutes["contribution.routes.ts"]:::backend
            RepositoryRoutes["repository.routes.ts"]:::backend
            StreakRoutes["streak.routes.ts"]:::backend
            UserRoutes["user.routes.ts"]:::backend
            GithubRoutes["github.routes.ts"]:::backend
        end
        subgraph "Controllers"
            AuthCtrl["auth.controller.ts"]:::backend
            ContributionCtrl["contribution.controller.ts"]:::backend
            RepositoryCtrl["repository.controller.ts"]:::backend
            StreakCtrl["streak.controller.ts"]:::backend
            UserCtrl["user.controller.ts"]:::backend
            GithubCtrl["github.controller.ts"]:::backend
        end
        subgraph "Middleware"
            AuthMW["auth.middleware.ts"]:::backend
            ErrorMW["errorHandler.ts"]:::backend
        end
        subgraph "Services"
            GitHubService["github.service.ts"]:::backend
            Scheduler["scheduler.service.ts"]:::backend
            MemoryDB["mongodb-memory-server.ts"]:::backend
        end
        subgraph "Models"
            UserModel["user.model.ts"]:::backend
            CommitModel["commit.model.ts"]:::backend
        end
        subgraph "Utils"
            AppError["appError.ts"]:::backend
            TimeUtils["timeUtils.ts"]:::backend
        end
        TempFiles["Temp Backdate Files (server/temp/)"]:::backend
        ConfigBE["Build & Config"]:::backend
    end

    %% Database & External
    MongoDB[(MongoDB Atlas)]:::db
    GitHubOAuth[("GitHub OAuth / API")]:::external

    %% Connections
    SPA -->|loads| Entry
    Entry -->|boots| Init
    Init -->|renders| Root
    Root --> Pages
    Root --> Components
    Pages --> Hooks
    Components --> Lib
    Lib -->|calls| ServerEntry

    ServerEntry --> DBConfig
    ServerEntry --> OAuthConfig
    ServerEntry --> AuthMW
    AuthMW -->|protects| AuthRoutes
    ServerEntry --> ErrorMW
    ServerEntry --> Routes
    AuthRoutes --> AuthCtrl
    ContributionRoutes --> ContributionCtrl
    RepositoryRoutes --> RepositoryCtrl
    StreakRoutes --> StreakCtrl
    UserRoutes --> UserCtrl
    GithubRoutes --> GithubCtrl
    Controllers --> Services
    Services --> Models
    Controllers -->|read/write| MongoDB
    Services -->|calls| GitHubOAuth
    Scheduler -->|jobs| Controllers
    Controllers --> TempFiles

    %% Data Flow
    SPA -->|REST API| AuthRoutes
    SPA -->|GET/POST| ContributionRoutes
    SPA -->|GET/POST| RepositoryRoutes
    SPA -->|GET/POST| StreakRoutes
    SPA -->|GET/POST| UserRoutes

    %% Click Events
    click Entry "https://github.com/geekyroshan/streak-webapp/blob/main/index.html"
    click Init "https://github.com/geekyroshan/streak-webapp/blob/main/src/main.tsx"
    click Root "https://github.com/geekyroshan/streak-webapp/blob/main/src/App.tsx"
    click Pages "https://github.com/geekyroshan/streak-webapp/tree/main/src/pages/"
    click Components "https://github.com/geekyroshan/streak-webapp/tree/main/src/components/"
    click Hooks "https://github.com/geekyroshan/streak-webapp/tree/main/src/hooks/"
    click Lib "https://github.com/geekyroshan/streak-webapp/tree/main/src/lib/"
    click Assets "https://github.com/geekyroshan/streak-webapp/tree/main/public/"
    click ConfigFE "https://github.com/geekyroshan/streak-webapp/blob/main/tailwind.config.ts"
    click ServerEntry "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/index.ts"
    click DBConfig "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/config/database.ts"
    click OAuthConfig "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/config/github.ts"
    click AuthRoutes "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/routes/auth.routes.ts"
    click ContributionRoutes "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/routes/contribution.routes.ts"
    click RepositoryRoutes "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/routes/repository.routes.ts"
    click StreakRoutes "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/routes/streak.routes.ts"
    click UserRoutes "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/routes/user.routes.ts"
    click GithubRoutes "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/routes/github.routes.ts"
    click AuthCtrl "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/controllers/auth.controller.ts"
    click ContributionCtrl "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/controllers/contribution.controller.ts"
    click RepositoryCtrl "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/controllers/repository.controller.ts"
    click StreakCtrl "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/controllers/streak.controller.ts"
    click UserCtrl "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/controllers/user.controller.ts"
    click GithubCtrl "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/controllers/github.controller.ts"
    click AuthMW "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/middleware/auth.middleware.ts"
    click ErrorMW "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/middleware/errorHandler.ts"
    click GitHubService "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/services/github.service.ts"
    click Scheduler "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/services/scheduler.service.ts"
    click MemoryDB "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/services/mongodb-memory-server.ts"
    click UserModel "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/models/user.model.ts"
    click CommitModel "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/models/commit.model.ts"
    click AppError "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/utils/appError.ts"
    click TimeUtils "https://github.com/geekyroshan/streak-webapp/blob/main/server/src/utils/timeUtils.ts"
    click TempFiles "https://github.com/geekyroshan/streak-webapp/tree/main/server/temp/"
    click ConfigBE "https://github.com/geekyroshan/streak-webapp/blob/main/server/tsconfig.json"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085
    classDef backend fill:#d4edda,stroke:#155724,color:#155724
    classDef db fill:#fff3cd,stroke:#856404,color:#856404
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24
```
