# tahminator/codebloom architecture

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

- Interactive diagram: https://gitdiagram.com/tahminator/codebloom
- Repository: https://github.com/tahminator/codebloom

## Overview

##### Project type and purpose
- This is a full-stack web application named CodeBloom.
- Purpose: Track users’ LeetCode activity, rank them on leaderboards, present daily challenges (POTD), send announcements via Discord/email, and allow admin management.

##### File structure
- Top-level:
- js/… → React + TypeScript frontend (Vite)
- src/main/java/… → Spring Boot backend (REST controllers, service, data layers)
- db/migration → Flyway SQL migrations for PostgreSQL
- infra/Dockerfile, Makefile, .env.example → containerization and deployment
- docs/, .github/ → CICD, tests, docs
- Patterns:
- MVC-style backend: Controllers → Services → Repositories → Models
- Scheduler modules under common/scheduled → background jobs (POTD setter, submission poller, weekly leaderboard)
- JDA integration module for Discord
- External-API handlers: LeetCode API, Email clients, JWT
- Redis client abstraction (SimpleRedis) for caching/session

##### README
- Confirms tech stack: React + React Query + Mantine + Tailwind on front end; Spring Boot + PostgreSQL + Docker on back end; deployed on DigitalOcean; error reporting via Sentry.

##### Main components & their interactions
a. Frontend (browser)
- React SPA served via Vite.
- Uses React Query to call REST API over HTTPS.
- Handles routing (React Router), UI (Mantine + Tailwind).
b. Backend (Spring Boot)
- REST Controllers (AuthController, LeaderboardController, etc.)
- Service layer (LeetCodeApiHandler, SubmissionsHandler, ScoreCalculator, Email, JWTClient)
- Data layer (Flyway migrations → PostgreSQL; Repositories wrapping SQL; SimpleRedis cache)
- Scheduler tasks (PotdSetter, SubmissionScheduler, WeeklyLeaderboard)
- JDA module for pushing messages to Discord via Discord API
c. Database & Cache
- PostgreSQL with Flyway migrations
- Redis (via SimpleRedis) for caching sessions or rate limits
d. External services
- LeetCode API for fetching user profile, submissions, POTD
- Discord via JDA (bot for announcements, weekly updates)
- Email providers (Codebloom official, GitHub OAuth)
- Sentry for error reporting
- DigitalOcean (hosting)

##### Architectural patterns/design principles
- 3-Tier separation: UI (frontend) ↔ API (controllers & services) ↔ Data (DB & cache)
- Dependency Injection (Spring) in backend
- Repository pattern for database access
- Scheduler for CRON-style tasks
- Adapter pattern for external services (LeetCode, Email, Discord)
- JWT-based auth, session persistence in DB

##### Essential architectural elements to capture
- Client-side UI + state management (React Query)
- API entrypoints + security (JWT, session)
- Business logic (score calculation, POTD, announcements)
- Data persistence (Flyway migrations, schemas)
- Caching layer (Redis)
- Scheduled jobs (POTD, subscription, weekly leaderboard)
- External integrations (LeetCode, Discord, Email, Sentry)
- Infrastructure/deployment (Docker, DigitalOcean)

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Layer
    subgraph "Client Layer"
        User["User"]:::user
        Browser["Browser (React SPA)"]:::frontend
    end
    User --> Browser

    click Browser "https://github.com/tahminator/codebloom/tree/main/js/src/"

    %% API Layer
    subgraph "API Layer"
        subgraph "Spring Boot Application"
            %% Controllers
            subgraph "Controllers"
                AuthController["AuthController"]:::api
                LeaderboardController["LeaderboardController"]:::api
                SubmissionController["SubmissionController"]:::api
                AnnouncementController["AnnouncementController"]:::api
                AdminController["AdminController"]:::api
                UserController["UserController"]:::api
            end

            %% Services
            subgraph "Service Layer"
                LeetCodeApiHandlerI["LeetcodeApiHandler (Interface)"]:::service
                DefaultLeetCodeApiHandler["DefaultLeetcodeApiHandler"]:::service
                ScoreCalculator["ScoreCalculator"]:::service
                SubmissionsHandler["SubmissionsHandler"]:::service
                OfficialEmail["OfficialCodebloomEmail"]:::service
                GithubEmail["GithubOAuthEmail"]:::service
                JWTClientI["JWTClient (Interface)"]:::service
                JWTClientImpl["JWTClientImpl"]:::service
                SimpleRedis["SimpleRedis"]:::service
            end

            %% Repositories & Models
            subgraph "Data Layer Components"
                Flyway["Flyway Migrations"]:::datastore
                Models["DB Models"]:::data
                AnnouncementRepo["AnnouncementRepository"]:::data
                AuthRepo["AuthRepository"]:::data
                LeaderboardRepo["LeaderboardRepository"]:::data
                POTDRepo["POTDRepository"]:::data
                QuestionRepo["QuestionRepository"]:::data
                SessionRepo["SessionRepository"]:::data
                UserRepo["UserRepository"]:::data
                UserTagRepo["UserTagRepository"]:::data
                WeeklyMsgRepo["WeeklyMessageRepository"]:::data
            end

            %% Schedulers
            subgraph "Scheduled Jobs"
                PotdSetter["PotdSetter"]:::schedule
                SubmissionScheduler["SubmissionScheduler"]:::schedule
                WeeklyLeaderboard["WeeklyLeaderboard"]:::schedule
                AuthStealer["LeetcodeAuthStealer"]:::schedule
            end
        end
    end

    %% Data Stores
    subgraph "Data Stores"
        Postgres["PostgreSQL"]:::datastore
        Redis["Redis Cache"]:::datastore
    end

    %% External Services
    subgraph "External Integrations"
        LeetCodeAPI["LeetCode API"]:::external
        DiscordAPI["Discord API"]:::external
        EmailSMTP["Email Providers"]:::external
        Sentry["Sentry"]:::external
        DigitalOcean["DigitalOcean Hosting"]:::external
    end

    %% Data Flows
    Browser -->|"HTTPS/JSON"| AuthController
    Browser -->|"HTTPS/JSON"| LeaderboardController
    Browser -->|"HTTPS/JSON"| SubmissionController
    Browser -->|"HTTPS/JSON"| AnnouncementController
    Browser -->|"HTTPS/JSON"| AdminController
    Browser -->|"HTTPS/JSON"| UserController

    %% Controller to Service
    AuthController -->|calls| JWTClientI
    AuthController -->|calls| AuthRepo
    LeaderboardController -->|calls| LeaderboardRepo
    SubmissionController -->|calls| SubmissionsHandler
    AnnouncementController -->|calls| AnnouncementRepo
    AdminController -->|calls| LeetCodeApiHandlerI
    UserController -->|calls| UserRepo

    %% Service interactions
    LeetCodeApiHandlerI --> DefaultLeetCodeApiHandler
    DefaultLeetCodeApiHandler -->|HTTPS/JSON| LeetCodeAPI
    SubmissionsHandler -->|JDBC/SQL| Postgres
    ScoreCalculator -->|reads| Models
    OfficialEmail -->|SMTP| EmailSMTP
    GithubEmail -->|OAuth| EmailSMTP
    JWTClientI --> JWTClientImpl
    JWTClientImpl -->|signs tokens| Models
    SimpleRedis -->|cache| Redis

    %% Repos to DB
    AnnouncementRepo -->|JDBC/SQL| Postgres
    AuthRepo -->|JDBC/SQL| Postgres
    LeaderboardRepo -->|JDBC/SQL| Postgres
    POTDRepo -->|JDBC/SQL| Postgres
    QuestionRepo -->|JDBC/SQL| Postgres
    SessionRepo -->|JDBC/SQL| Postgres
    UserRepo -->|JDBC/SQL| Postgres
    UserTagRepo -->|JDBC/SQL| Postgres
    WeeklyMsgRepo -->|JDBC/SQL| Postgres
    Flyway -->|migrations| Postgres

    %% Schedulers flows
    PotdSetter -->|sets daily challenge| POTDRepo
    PotdSetter -->|notifies| DiscordAPI
    SubmissionScheduler -->|polls| LeetCodeAPI
    SubmissionScheduler -->|updates| SubmissionController
    WeeklyLeaderboard -->|generates| LeaderboardRepo
    WeeklyLeaderboard -->|posts| DiscordAPI
    AuthStealer -->|refreshes| LeetCodeAPI

    %% Error reporting
    SpringBootError["Error Handler"]:::api -->|reports| Sentry

    %% Hosting
    SpringBootApp["Spring Boot Application"] -.->|deployed on| DigitalOcean

    %% Click events
    click AuthController "https://github.com/tahminator/codebloom/blob/main/src/main/java/com/patina/codebloom/api/auth/AuthController.java"
    click LeaderboardController "https://github.com/tahminator/codebloom/blob/main/src/main/java/com/patina/codebloom/api/leaderboard/LeaderboardController.java"
    click SubmissionController "https://github.com/tahminator/codebloom/blob/main/src/main/java/com/patina/codebloom/api/submission/SubmissionController.java"
    click AnnouncementController "https://github.com/tahminator/codebloom/blob/main/src/main/java/com/patina/codebloom/api/announcement/AnnouncementController.java"
    click AdminController "https://github.com/tahminator/codebloom/blob/main/src/main/java/com/patina/codebloom/api/admin/AdminController.java"
    click UserController "https://github.com/tahminator/codebloom/blob/main/src/main/java/com/patina/codebloom/api/user/UserController.java"
    click LeetCodeApiHandlerI "https://github.com/tahminator/codebloom/blob/main/src/main/java/com/patina/codebloom/common/leetcode/LeetcodeApiHandler.java"
    click DefaultLeetCodeApiHandler "https://github.com/tahminator/codebloom/blob/main/src/main/java/com/patina/codebloom/common/leetcode/DefaultLeetcodeApiHandler.java"
    click ScoreCalculator "https://github.com/tahminator/codebloom/blob/main/src/main/java/com/patina/codebloom/common/leetcode/score/ScoreCalculator.java"
    click SubmissionsHandler "https://github.com/tahminator/codebloom/blob/main/src/main/java/com/patina/codebloom/common/submissions/SubmissionsHandler.java"
    click OfficialEmail "https://github.com/tahminator/codebloom/blob/main/src/main/java/com/patina/codebloom/common/email/client/codebloom/OfficialCodebloomEmail.java"
    click GithubEmail "https://github.com/tahminator/codebloom/blob/main/src/main/java/com/patina/codebloom/common/email/client/github/GithubOAuthEmail.java"
    click JWTClientI "https://github.com/tahminator/codebloom/blob/main/src/main/java/com/patina/codebloom/common/jwt/JWTClient.java"
    click JWTClientImpl "https://github.com/tahminator/codebloom/blob/main/src/main/java/com/patina/codebloom/common/jwt/impl/JWTClientImpl.java"
    click SimpleRedis "https://github.com/tahminator/codebloom/blob/main/src/main/java/com/patina/codebloom/common/simpleredis/SimpleRedis.java"
    click Flyway "https://github.com/tahminator/codebloom/tree/main/db/migration/"
    click Dockerfile "https://github.com/tahminator/codebloom/tree/main/infra/Dockerfile"
    click Makefile "https://github.com/tahminator/codebloom/tree/main/Makefile"
    click Env "https://github.com/tahminator/codebloom/blob/main/ .env.example"
    click CICD "https://github.com/tahminator/codebloom/blob/main/ .github/workflows/ci-cd.yml"

    %% Styles
    classDef user fill:#a6cee3,stroke:#1f78b4,stroke-width:2px
    classDef frontend fill:#1f78b4,stroke:#08306b,stroke-width:2px
    classDef api fill:#33a02c,stroke:#006400,stroke-width:2px
    classDef service fill:#b2df8a,stroke:#228B22,stroke-width:2px
    classDef data fill:#fb9a99,stroke:#B22222,stroke-width:2px
    classDef datastore fill:#ff7f00,stroke:#8B4513,stroke-width:2px
    classDef schedule fill:#fdbf6f,stroke:#FF8C00,stroke-width:2px
    classDef external fill:#cccccc,stroke:#696969,stroke-width:2px
```
