# waterrmalann/bit-warriors-backend architecture

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

- Interactive diagram: https://gitdiagram.com/waterrmalann/bit-warriors-backend
- Repository: https://github.com/waterrmalann/bit-warriors-backend

## Overview

##### Project type and purpose
- This is a service-oriented Node.js backend for **BitWarriors**, an AI-powered competitive coding platform (inspired by LeetCode/CodeWars).
- It’s composed of multiple discrete microservices (User, Problem, Submission, Test, Gateway, CES) communicating synchronously via an API Gateway and asynchronously via Apache Kafka.
- Each service follows a clean/hexagonal architecture: layers for Application (use-cases), Domain (entities, interfaces), Infrastructure (database, messaging, webserver), Interfaces (controllers, routes, consumers).

##### File structure
- Top-level services:
– gateway-dev (API gateway, JWT auth middleware, Express proxy)
– user-service (auth, profiles, OAuth, MFA, JWT, Kafka consumer/producer, MongoDB)
– problem-service (CRUD problems, voting, Kafka events, MongoDB)
– submission-service (submit/run problems, leaderboards, Kafka events, MongoDB)
– test-service (code evaluation via Judge0 or V8 sandbox, used internally by submission-service)
– ces-dev (Code Execution Sandbox container for safe execution of arbitrary code)
- infra/helm: Helm charts for each service, Kafka, MongoDB.
- Build workflows: GitHub Actions for each service.

##### Key insights from README
- API Gateway handles authentication (JWT) and proxies to downstream services.
- Kafka is the asynchronous message broker connecting services (e.g., Problem → Submission, Submission → User for stats, etc.).
- Each service has its own MongoDB schema (statefulset) and secrets.
- Containerized with Docker, orchestrated via Kubernetes (Helm charts).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients and Admin
    Clients["Clients / Frontend"]:::external
    AdminService["Admin Service"]:::external

    subgraph "Kubernetes Cluster"
        direction TB

        %% API Gateway
        Gateway["API Gateway"]:::gateway
        AuthMiddleware["Auth Middleware"]:::gateway

        %% Kafka Broker
        Kafka["Apache Kafka"]:::broker

        %% User Service
        subgraph "User Service"
            direction TB
            UserEntry["Entry Point"]:::microservice
            UserApp["Application Layer"]:::microservice
            UserDomain["Domain Layer"]:::microservice
            UserInfra["Infrastructure Layer"]:::microservice
            UserInterfaces["Interfaces"]:::microservice
            UserDB["MongoDB (User)"]:::database
        end

        %% Problem Service
        subgraph "Problem Service"
            direction TB
            ProblemEntry["Entry Point"]:::microservice
            ProblemApp["Application Layer"]:::microservice
            ProblemDomain["Domain Layer"]:::microservice
            ProblemInfra["Infrastructure Layer"]:::microservice
            ProblemInterfaces["Interfaces"]:::microservice
            ProblemDB["MongoDB (Problem)"]:::database
        end

        %% Submission Service
        subgraph "Submission Service"
            direction TB
            SubmissionEntry["Entry Point"]:::microservice
            SubmissionApp["Application Layer"]:::microservice
            SubmissionDomain["Domain Layer"]:::microservice
            SubmissionInfra["Infrastructure Layer"]:::microservice
            SubmissionInterfaces["Interfaces"]:::microservice
            SubmissionDB["MongoDB (Submission)"]:::database
        end

        %% Test Service + CES group
        subgraph "Test & Sandbox"
            direction TB
            subgraph "Test Service"
                TestEntry["Entry Point"]:::microservice
                TestApp["Application Layer"]:::microservice
                TestDomain["Domain Layer"]:::microservice
                TestInfra["Infrastructure Layer"]:::microservice
                TestInterfaces["Interfaces"]:::microservice
                TestDB["MongoDB (Test)"]:::database
            end
            subgraph "Code Execution Sandbox (CES)"
                CES["CES Container"]:::sandbox
            end
        end

        %% Helm Charts (as notes)
        infraNote["Helm Charts / K8s Deployments"]:::note
    end

    %% Synchronous HTTP paths
    Clients -->|"HTTP JWT"| Gateway
    Gateway -->|"proxy"| UserEntry
    Gateway -->|"proxy"| ProblemEntry
    Gateway -->|"proxy"| SubmissionEntry
    AdminService -->|"HTTP JWT"| Gateway

    %% Auth Middleware integration
    Gateway --> AuthMiddleware

    %% Service to MongoDB
    UserEntry --> UserDB
    ProblemEntry --> ProblemDB
    SubmissionEntry --> SubmissionDB
    TestEntry --> TestDB

    %% Submission -> Test Service sync call
    SubmissionEntry -->|"runTests()"| TestEntry
    TestEntry -->|"evaluate code"| CES

    %% Kafka async events
    UserEntry <--->|"UserEvents"| Kafka
    ProblemEntry <--->|"problem.added / problem.updated"| Kafka
    SubmissionEntry <--->|"submission.created"| Kafka
    TestEntry <--->|"tests.updated"| Kafka

    %% Helm charts linkage
    infraNote --> Gateway
    infraNote --> UserEntry
    infraNote --> ProblemEntry
    infraNote --> SubmissionEntry
    infraNote --> TestEntry
    infraNote --> CES

    %% Click events: gateway
    click Gateway "https://github.com/waterrmalann/bit-warriors-backend/blob/main/gateway-dev/index.js"
    click AuthMiddleware "https://github.com/waterrmalann/bit-warriors-backend/blob/main/gateway-dev/authenticateMiddleware.js"

    %% User Service mapping
    click UserEntry "https://github.com/waterrmalann/bit-warriors-backend/blob/main/user-service/index.js"
    click UserApp "https://github.com/waterrmalann/bit-warriors-backend/tree/main/user-service/lib/application/use-cases"
    click UserDomain "https://github.com/waterrmalann/bit-warriors-backend/tree/main/user-service/lib/domain"
    click UserInfra "https://github.com/waterrmalann/bit-warriors-backend/tree/main/user-service/lib/infrastructure"
    click UserInterfaces "https://github.com/waterrmalann/bit-warriors-backend/tree/main/user-service/lib/interfaces"

    %% Problem Service mapping
    click ProblemEntry "https://github.com/waterrmalann/bit-warriors-backend/blob/main/problem-service/index.js"
    click ProblemApp "https://github.com/waterrmalann/bit-warriors-backend/tree/main/problem-service/lib/application/use-cases"
    click ProblemDomain "https://github.com/waterrmalann/bit-warriors-backend/tree/main/problem-service/lib/domain"
    click ProblemInfra "https://github.com/waterrmalann/bit-warriors-backend/tree/main/problem-service/lib/infrastructure"
    click ProblemInterfaces "https://github.com/waterrmalann/bit-warriors-backend/tree/main/problem-service/lib/interfaces"

    %% Submission Service mapping
    click SubmissionEntry "https://github.com/waterrmalann/bit-warriors-backend/blob/main/submission-service/index.js"
    click SubmissionApp "https://github.com/waterrmalann/bit-warriors-backend/tree/main/submission-service/lib/application/use-cases"
    click SubmissionDomain "https://github.com/waterrmalann/bit-warriors-backend/tree/main/submission-service/lib/domain"
    click SubmissionInfra "https://github.com/waterrmalann/bit-warriors-backend/tree/main/submission-service/lib/infrastructure"
    click SubmissionInterfaces "https://github.com/waterrmalann/bit-warriors-backend/tree/main/submission-service/lib/interfaces"

    %% Test Service mapping
    click TestEntry "https://github.com/waterrmalann/bit-warriors-backend/blob/main/test-service/index.js"
    click TestApp "https://github.com/waterrmalann/bit-warriors-backend/tree/main/test-service/lib/application/use-cases"
    click TestDomain "https://github.com/waterrmalann/bit-warriors-backend/tree/main/test-service/lib/domain"
    click TestInfra "https://github.com/waterrmalann/bit-warriors-backend/tree/main/test-service/lib/infrastructure"
    click TestInterfaces "https://github.com/waterrmalann/bit-warriors-backend/tree/main/test-service/lib/interfaces"

    %% CES mapping
    click CES "https://github.com/waterrmalann/bit-warriors-backend/blob/main/ces-dev/index.js"
    click CES "https://github.com/waterrmalann/bit-warriors-backend/tree/main/ces-dev/Dockerfile"
    click CES "https://github.com/waterrmalann/bit-warriors-backend/blob/main/ces-dev/package.json"

    %% Helm charts mapping
    click infraNote "https://github.com/waterrmalann/bit-warriors-backend/tree/main/infra/helm/kafka"
    click infraNote "https://github.com/waterrmalann/bit-warriors-backend/tree/main/infra/helm/mongodb"
    click infraNote "https://github.com/waterrmalann/bit-warriors-backend/tree/main/infra/helm/gateway-dev"
    click infraNote "https://github.com/waterrmalann/bit-warriors-backend/tree/main/infra/helm/user-service"
    click infraNote "https://github.com/waterrmalann/bit-warriors-backend/tree/main/infra/helm/problem-service"
    click infraNote "https://github.com/waterrmalann/bit-warriors-backend/tree/main/infra/helm/submission-service"
    click infraNote "https://github.com/waterrmalann/bit-warriors-backend/tree/main/infra/helm/test-service"
    click infraNote "https://github.com/waterrmalann/bit-warriors-backend/tree/main/infra/helm/ces-dev"
    click infraNote "https://github.com/waterrmalann/bit-warriors-backend/tree/main/infra/helm/admin-service"

    %% CI/CD workflows mapping
    click UserEntry "https://github.com/waterrmalann/bit-warriors-backend/blob/main/.github/workflows/build-user-service.yml"
    click ProblemEntry "https://github.com/waterrmalann/bit-warriors-backend/blob/main/.github/workflows/build-problem-service.yml"
    click SubmissionEntry "https://github.com/waterrmalann/bit-warriors-backend/blob/main/.github/workflows/build-submission-service.yml"
    click TestEntry "https://github.com/waterrmalann/bit-warriors-backend/blob/main/.github/workflows/build-test-service.yml"

    %% Styles
    classDef microservice fill:#D6E9FE,stroke:#3B82F6,stroke-width:1px
    classDef gateway fill:#E8F0FE,stroke:#1A73E8,stroke-width:1px
    classDef database fill:#F1F8E9,stroke:#8BC34A,stroke-width:1px,shape:cylinder
    classDef broker fill:#FFF4E5,stroke:#FB8C00,stroke-width:1px
    classDef sandbox fill:#F3E5F5,stroke:#8E24AA,stroke-width:1px
    classDef external fill:#ECEFF1,stroke:#607D8B,stroke-width:1px,stroke-dasharray: 5 5
    classDef note fill:#FFFFFF,stroke:#BDBDBD,stroke-width:1px,stroke-dasharray: 2 2
    classDef interfaces fill:#D6E9FE
    class infraNote note
```
