# eintoast/mariokart_frontend architecture

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

- Interactive diagram: https://gitdiagram.com/eintoast/mariokart_frontend
- Repository: https://github.com/eintoast/mariokart_frontend

## Overview

##### Main components
- Frontend UI Layer – Built with Ionic and React (TypeScript/TSX files in /src). This includes:
- Pages (user-facing screens like LoginTeam, Survey, various Tab pages)
- Admin Pages (under /src/pages/admin such as AdminRouter, Dashboard, and various admin management pages)
- Components (such as Header, QRCodeComponent, Toast, modals for survey/team management, and specialized components for rounds and graphs)
- API Communication Layer – Found within /src/util/api and its subdirectories. This defines how the app interacts with back-end endpoints, with separate modules for registration, schedule, settings, survey, and user services.
- Service Layer – In /src/util/service, mirroring the API modules to encapsulate business logic for registration (both admin and public), schedule, survey, settings, user functionalities, and even cookies and websockets. These services manage API calls and data flow across the app.
- Testing Infrastructure – Cypress is set up (cypress folder and configuration files) for end-to-end testing, which may be represented as part of the quality assurance component of the architecture.
- Build & Deployment Infrastructure – The Dockerfile, .dockerignore, GitHub workflows, and configuration via Vite (vite.config.ts) indicate continuous integration/deployment and build tooling integrations.
- External Systems – A mock API service (using demo.json and instructions to load in MOCK API Tool) that represents where backend responses come from.

##### Relationships and interactions
- The UI Elements (Pages and Components) are the entry points users interact with. They call custom hooks (in /src/hooks) and make API calls via the API client modules.
- The API Communication Layer encapsulates request configurations and endpoints; this interfaces with the Service Layer, which contains the actual business-logic implementations.
- The Service Layer (with separate modules for registration, schedule, survey, etc.) processes data, handles cookies, manages state (using websockets for live updates), and delivers data back to UI components.
- The testing suite (Cypress) simulates user interactions across these components and ensures that the integration between UI and service layers works as expected.

##### Important architectural patterns and design principles
- Modularization – The separation of components, pages, API, and service modules reflects a modular architecture that supports scalability and easier maintenance.
- Separation of Concerns – UI components concentrate on rendering and user events; APIs and services handle data management and external communications.
- Use of External Tools – For instance, the reliance on Ionic’s framework, capacitor configuration (supporting mobile integration), and the use of mock servers for backend simulation.

##### Relevant technologies, frameworks, and libraries
- Ionic Framework and React for the frontend.
- TypeScript for type-safe development.
- Cypress for end-to-end testing.
- Docker and GitHub Actions for containerization and CI/CD.
- Vite as the build tool.
- WebSockets for realtime updates.
- External mock API tools (Mockoon) used during development.

- Clear labels for each major component (UI, API Client, Services, Testing, External Mock API, Build/Deployment Infrastructure).
- Internal module interactions (such as admin versus public functionality branches) clearly to show separation of concerns.

## Diagram (Mermaid)

```mermaid
graph TD
    A["Frontend UI Layer"]:::ui
    B["Custom Hooks"]:::hooks
    C["API Communication Layer"]:::api
    D["Service Layer"]:::service
    F["Testing Infrastructure"]:::testing
    G["Build & Deployment Infrastructure"]:::deployment

    A -->|"calls"| B
    B -->|"invokes"| C
    C -->|"processes"| D
    C -->|"gets_data_from"| EX1

    F -->|"tests"| A
    F -->|"tests"| C
    F -->|"tests"| D

    G -->|"deploys"| A
    G -->|"deploys"| C
    G -->|"deploys"| D

    subgraph "Frontend UI Layer Details"
        subgraph "User Pages"
            UI1["LoginTeam"]:::ui
            UI2["Survey"]:::ui
            UI3["Tab1"]:::ui
            UI4["Tab2"]:::ui
            UI5["Tab3"]:::ui
            UI6["Tab4"]:::ui
        end
        subgraph "Admin Pages"
            ADMIN1["AdminRouter"]:::ui
            ADMIN2["Dashboard"]:::ui
            ADMIN3["Control"]:::ui
            ADMIN4["AdminLogin"]:::ui
        end
        subgraph "UI Components"
            COMP1["Header"]:::ui
            COMP2["QRCodeComponent"]:::ui
            COMP3["Toast"]:::ui
            COMP4["Modals"]:::ui
            COMP5["Rounds"]:::ui
            COMP6["Graphs"]:::ui
        end
    end

    subgraph "Custom Hooks Details"
        CH1["useRoundData"]:::hooks
        CH2["useWebSocketConnection"]:::hooks
    end

    subgraph "Testing Infrastructure Details"
        TEST1["Cypress Tests"]:::testing
        TEST2["Cypress Config"]:::testing
    end

    subgraph "Build & Deployment Details"
        BD1["Dockerfile"]:::deployment
        BD2["GitHub Workflows"]:::deployment
        BD3["Vite Config"]:::deployment
    end

    subgraph "External Systems"
        EX1["Mock API"]:::external
        EX2["Assets & Fonts"]:::external
    end

click UI1 "https://github.com/eintoast/mariokart_frontend/blob/main//src/pages/LoginTeam.tsx"
click UI2 "https://github.com/eintoast/mariokart_frontend/blob/main//src/pages/Survey.tsx"
click UI3 "https://github.com/eintoast/mariokart_frontend/blob/main//src/pages/Tab1.tsx"
click UI4 "https://github.com/eintoast/mariokart_frontend/blob/main//src/pages/Tab2.tsx"
click UI5 "https://github.com/eintoast/mariokart_frontend/blob/main//src/pages/Tab3.tsx"
click UI6 "https://github.com/eintoast/mariokart_frontend/blob/main//src/pages/Tab4.tsx"

click ADMIN1 "https://github.com/eintoast/mariokart_frontend/blob/main//src/pages/admin/AdminRouter.tsx"
click ADMIN2 "https://github.com/eintoast/mariokart_frontend/blob/main//src/pages/admin/Dashboard.tsx"
click ADMIN3 "https://github.com/eintoast/mariokart_frontend/blob/main//src/pages/admin/Control.tsx"
click ADMIN4 "https://github.com/eintoast/mariokart_frontend/blob/main//src/pages/admin/Login.tsx"

click COMP1 "https://github.com/eintoast/mariokart_frontend/tree/main//src/components"
click COMP2 "https://github.com/eintoast/mariokart_frontend/tree/main//src/components"
click COMP3 "https://github.com/eintoast/mariokart_frontend/tree/main//src/components"
click COMP4 "https://github.com/eintoast/mariokart_frontend/tree/main//src/components"
click COMP5 "https://github.com/eintoast/mariokart_frontend/tree/main//src/components"
click COMP6 "https://github.com/eintoast/mariokart_frontend/tree/main//src/components"

click CH1 "https://github.com/eintoast/mariokart_frontend/blob/main//src/hooks/useRoundData.ts"
click CH2 "https://github.com/eintoast/mariokart_frontend/blob/main//src/hooks/useWebSocketConnection.ts"

click C "https://github.com/eintoast/mariokart_frontend/tree/main//src/util/api"
click D "https://github.com/eintoast/mariokart_frontend/tree/main//src/util/service"

click TEST1 "https://github.com/eintoast/mariokart_frontend/tree/main//cypress"
click TEST2 "https://github.com/eintoast/mariokart_frontend/blob/main//cypress.config.ts"

click BD1 "https://github.com/eintoast/mariokart_frontend/tree/main/Dockerfile"
click BD2 "https://github.com/eintoast/mariokart_frontend/tree/main//.github/workflows"
click BD3 "https://github.com/eintoast/mariokart_frontend/blob/main/vite.config.ts"

click EX1 "https://github.com/eintoast/mariokart_frontend/blob/main//demo.json"
click EX2 "https://github.com/eintoast/mariokart_frontend/tree/main//public/fonts"

classDef ui fill:#93c5fd,stroke:#1e40af,stroke-width:2px;
classDef hooks fill:#fcd34d,stroke:#92400e,stroke-width:2px;
classDef api fill:#a7f3d0,stroke:#065f46,stroke-width:2px;
classDef service fill:#fca5a5,stroke:#991b1b,stroke-width:2px;
classDef external fill:#fef08a,stroke:#ca8a04,stroke-width:2px;
classDef testing fill:#f0abfc,stroke:#6b21a8,stroke-width:2px;
classDef deployment fill:#c7d2fe,stroke:#3730a3,stroke-width:2px;
```
