# bux42/tmdojo architecture

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

- Interactive diagram: https://gitdiagram.com/bux42/tmdojo
- Repository: https://github.com/bux42/tmdojo

## Overview

- a React/Next.js front-end inside the /app folder,
- a Node.js back-end inside the /server folder, and
- a plugin (for Openplanet) for in-game data recording (mentioned in the README, though its files aren’t visible in the file tree).

##### Main Components
a. Frontend:
– Label a “Frontend” component representing the React/Next.js application. Note that it includes pages, components (e.g., common, landing, mapStats, maps, users, viewer), contexts (e.g., AuthContext, SettingsContext), and various libs for API calls and utilities.
b. Backend:
– Label a “Backend” component representing your Node.js/Express server. Key parts include the API routes (auth, maps, replays, users, etc.), middleware (authentication, logging), utility libraries (for Discord webhooks, database utilities, logging), and a caching mechanism.
c. Plugin:
– Represent the Openplanet plugin as an external or integrated module that captures in-game racing data and reports to the backend.
d. External Services:
– Optionally add external integrations (for example, Discord integration via webhook notifications) that interact with the backend.

##### Detail the Relationships and Interactions
- That the Backend interacts internally with its database (referenced by /server/src/lib/db.ts) and uses middleware for authentication and logging.
- Plugin sending racing data to the Backend for aggregation and storage.
- Flow of notifications/alerts from the Backend to external services (like Discord).

##### Architectural Patterns and Principles
- For the frontend, note that Next.js is likely used for server-side rendering and routing, which implies an MVC-like separation of pages, components, and context providers.
- For the backend, highlight the use of modular routing, middleware for request handling, and the service layer encapsulated in libraries (e.g., for database access and webhook notifications). Use of singletons for global data (as seen in /server/src/lib/singletons/) also indicates a design choice for centralizing shared states.
- Clear separation of concerns (UI logic in the frontend, business logic and API handling in the backend, and dedicated data capture in the plugin).

##### Relevant Technologies, Frameworks, and Libraries
- Frontend: React, Next.js, Tailwind CSS, React Query.
- Backend: Node.js, Express (inferred from routing and middleware structure), and integrations for Discord webhooks.
- Plugin: Openplanet (per the README).
- Additional utilities: Various custom libraries for charts, constants, authentication, logging, etc.

##### What
- Notes or annotations for key files or directories that are critical to the feature implementation (e.g., the API hooks in /app/lib/api/reactQuery, or the cache and logger modules in the server).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        FE_Main["Frontend (React/Next.js)"]:::frontend
        FE_Pages["Pages"]:::frontend
        FE_Components["Components"]:::frontend
        FE_API["API Lib"]:::frontend
        FE_Contexts["Contexts"]:::frontend
    end

    subgraph "Backend Layer"
        BE_Main["Backend (Node.js/Express)"]:::backend
        BE_Routes["API Routes"]:::backend
        BE_Middleware["Middleware (Auth&Logging)"]:::backend
        BE_Utilities["Utilities (Database, Webhooks, Cache)"]:::backend
    end

    Plugin["Plugin (Openplanet)"]:::plugin
    EX_Discord["Discord Webhooks"]:::external

    %% Connections between components
    FE_API -->|"APIcalls"| BE_Routes
    Plugin -->|"RacingData"| BE_Routes
    BE_Routes -->|"processesThrough"| BE_Middleware
    BE_Routes -->|"invokes"| BE_Utilities
    BE_Utilities -->|"notifies"| EX_Discord

    %% Click Events for Frontend
    click FE_Main "https://github.com/bux42/tmdojo/tree/staging//app"
    click FE_Pages "https://github.com/bux42/tmdojo/tree/staging//app/pages"
    click FE_Components "https://github.com/bux42/tmdojo/tree/staging//app/components"
    click FE_API "https://github.com/bux42/tmdojo/tree/staging//app/lib/api"
    click FE_Contexts "https://github.com/bux42/tmdojo/tree/staging//app/lib/contexts"

    %% Click Events for Backend
    click BE_Main "https://github.com/bux42/tmdojo/tree/staging//server"
    click BE_Routes "https://github.com/bux42/tmdojo/tree/staging//server/src/routes"
    click BE_Middleware "https://github.com/bux42/tmdojo/tree/staging//server/src/middleware"
    click BE_Utilities "https://github.com/bux42/tmdojo/tree/staging//server/src/lib"

    %% Click Events for External Services
    click EX_Discord "https://github.com/bux42/tmdojo/tree/staging//server/src/lib/discordWebhooks"

    %% Styling
    classDef frontend fill:#ADD8E6,stroke:#0000FF,stroke-width:2px;
    classDef backend fill:#98FB98,stroke:#008000,stroke-width:2px;
    classDef plugin fill:#FFFFE0,stroke:#FFD700,stroke-width:2px;
    classDef external fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px;
```
