# antony-jacob817/cubora architecture

> Architecture diagram of the GitHub repository antony-jacob817/cubora, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/antony-jacob817/cubora
- Repository: https://github.com/antony-jacob817/cubora

## Overview

1. **Repository shape: two deployable applications**
   - The repo is split into a **frontend SPA** at the root and a separate **Node backend** in `cubora-backend/`.
   - The frontend is a **React + TypeScript + Vite** app.
   - The backend is an **Express-style API server** with its own models, middleware, routes, and service layer.

2. **Frontend is the user-facing application shell**
   - Entry points are `src/main.tsx` and `src/App.tsx`.
   - The app is organized by **pages** (`src/pages/...`) and **layouts** (`src/layouts/...`), with reusable UI under `src/components/...`.
   - `MainLayout` and `DashboardLayout` likely define the primary navigation and page framing for different app areas.

3. **Feature areas on the frontend**
   - The page tree suggests several major product surfaces: **landing**, **dashboard**, **practice/session flow**, **scanner/color correction**, **analytics**, **AI coach**, **community**, and **multiplayer**.
   - These are separated as page-level boundaries, implying route-driven navigation rather than a single monolithic screen.

4. **Rubik’s cube interaction and visualization layer**
   - `src/components/3d/` contains `AnimatedCube`, `CubeViewer`, `Cubie`, and `RubiksCube`, indicating a dedicated **3D cube rendering subsystem**.
   - This visualization is likely used by practice/scanning/solver experiences and is separate from standard UI components.

5. **Scanner and computer-vision pipeline on the client**
   - `src/pages/scanner/Scanner.tsx` and `ColorCorrection.tsx`, plus `src/services/colorDetector.ts` and `opencvLoader.ts`, show a client-side **camera + image processing pipeline**.
   - The browser likely captures video, loads OpenCV in the frontend, detects colors, and then performs correction/validation before feeding results into cube logic.

6. **Cube logic and validation are isolated from UI**
   - `src/utils/cubing.ts` and `cubeValidator.ts` hold core cube-domain logic, separate from components and pages.
   - This is an important architecture boundary: UI and camera inputs are transformed into cube state/move data through shared utility logic.

7. **Frontend interaction patterns**
   - Hooks such as `useCamera`, `useSolvePlayback`, and `useTimer` encapsulate stateful behavior and side effects.
   - Animation helpers (`src/components/animations`, `src/animations/variants.ts`) and generic UI primitives (`Button`, `Modal`, `Tooltip`, etc.) support consistent interaction without coupling business logic to presentation.

8. **Backend API responsibilities**
   - `cubora-backend/src/server.js` is the server entrypoint.
   - Routes are split into `authRoutes.js` and `solverRoutes.js`, suggesting two main API surfaces: **identity/session management** and **solver-related operations**.

9. **Backend service and middleware boundaries**
   - `src/middleware/auth.js` indicates protected endpoints and token/session enforcement.
   - `src/services/solverEngine.js` isolates the solving logic from route handlers, so request handling and algorithmic work are separated.

10. **Backend data model layer**
    - The backend defines models for `User`, `UserSettings`, `SolveHistory`, `LearningProgress`, `Achievement`, and `CubeScan`.
    - This implies persistence for **accounts**, **preferences**, **practice history**, **learning state**, **gamification**, and **scan records**.
    - `src/config/db.js` is the database connection boundary, likely tying the server to a document database.

11. **Primary data flows**
    - **Authentication flow:** frontend auth pages/components call backend auth routes; backend validates and persists user/session data.
    - **Practice/solve flow:** frontend cube UI and timers produce solve events; backend can store history and progress.
    - **Scanner flow:** frontend camera/OpenCV pipeline extracts cube colors, then cube utilities validate or normalize the result before downstream use.
    - **Solver flow:** frontend requests solver support from the backend; `solverEngine` computes output returned to the UI for playback/display.

12. **Product subsystems exposed in the UI**
    - `academy`, `coach`, `community`, `multiplayer`, and `analytics` page folders suggest the app is more than a solver: it combines **training content**, **guidance**, **social features**, and **performance tracking**.
    - The presence of progress/history/achievement models on the backend aligns with these higher-level user journeys.

13. **Operational and build tooling**
    - The frontend uses **Vite**, **TypeScript**, and **Tailwind** (`tailwind.config.ts`, `postcss.config.js`).
    - The backend has its own `package.json` and lockfile, meaning it is independently managed and likely started/deployed separately from the SPA.

Main entry points: [`src/layouts/DashboardLayout.tsx`](https://github.com/antony-jacob817/cubora/blob/main/src/layouts/DashboardLayout.tsx) (Dashboard layout), [`cubora-backend/src/server.js`](https://github.com/antony-jacob817/cubora/blob/main/cubora-backend/src/server.js) (Server), [`src/pages/practice/PracticeSession.tsx`](https://github.com/antony-jacob817/cubora/blob/main/src/pages/practice/PracticeSession.tsx) (Practice), [`cubora-backend/src/routes/authRoutes.js`](https://github.com/antony-jacob817/cubora/blob/main/cubora-backend/src/routes/authRoutes.js) (Auth API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend SPA"]
  node_main_entry["App shell<br/>entrypoint<br/>[main.tsx]"]
  node_app_routes["Router<br/>navigation<br/>[App.tsx]"]
  node_main_layout["Main layout<br/>[MainLayout.tsx]"]
  node_dashboard_layout["Dashboard layout"]
  node_landing_page["Landing<br/>page<br/>[LandingPage.tsx]"]
  node_dashboard_page["Dashboard<br/>page<br/>[Dashboard.tsx]"]
  node_practice_page["Practice<br/>page"]
  node_scanner_page["Scanner<br/>page<br/>[Scanner.tsx]"]
  node_analytics_page["Analytics<br/>page"]
  node_coach_page["AI coach<br/>page<br/>[AiCoach.tsx]"]
  node_community_page["Community<br/>page<br/>[CommunityHub.tsx]"]
  node_multiplayer_page["Multiplayer<br/>page<br/>[MultiplayerHub.tsx]"]
  node_cube_3d["3D cube<br/>visualization<br/>[RubiksCube.tsx]"]
  node_scanner_pipeline["Vision pipeline<br/>cv pipeline<br/>[colorDetector.ts]"]
  node_cube_logic["Cube logic<br/>domain utils<br/>[cubing.ts]"]
  node_solver_ui["Solver UI<br/>interaction"]
end

subgraph group_backend["Backend API"]
  node_auth_routes["Auth API<br/>route<br/>[authRoutes.js]"]
  node_solver_routes["Solver API<br/>route<br/>[solverRoutes.js]"]
  node_auth_middleware["Auth guard<br/>middleware<br/>[auth.js]"]
  node_solver_engine["Solver engine<br/>[solverEngine.js]"]
  node_user_models[("User data<br/>models<br/>[User.js]")]
  node_db_config["Database<br/>config<br/>[db.js]"]
  node_backend_server["Server<br/>entrypoint<br/>[server.js]"]
end

node_main_entry -->|"boots"| node_app_routes
node_app_routes -->|"uses"| node_main_layout
node_app_routes -->|"uses"| node_dashboard_layout
node_main_layout -->|"hosts"| node_landing_page
node_dashboard_layout -->|"hosts"| node_dashboard_page
node_dashboard_layout -->|"hosts"| node_practice_page
node_dashboard_layout -->|"hosts"| node_scanner_page
node_dashboard_layout -->|"hosts"| node_analytics_page
node_dashboard_layout -->|"hosts"| node_coach_page
node_dashboard_layout -->|"hosts"| node_community_page
node_dashboard_layout -->|"hosts"| node_multiplayer_page
node_practice_page -->|"drives"| node_cube_3d
node_practice_page -->|"controls"| node_solver_ui
node_scanner_page -->|"uses"| node_scanner_pipeline
node_scanner_pipeline -->|"normalizes"| node_cube_logic
node_cube_3d -->|"represents"| node_cube_logic
node_solver_ui -->|"plays back"| node_cube_3d
node_auth_routes -->|"protected by"| node_auth_middleware
node_solver_routes -->|"delegates"| node_solver_engine
node_auth_routes -->|"persists"| node_user_models
node_solver_routes -->|"records"| node_user_models
node_backend_server -->|"mounts"| node_auth_routes
node_backend_server -->|"mounts"| node_solver_routes
node_backend_server -->|"connects"| node_db_config
node_backend_server -->|"loads"| node_user_models
node_dashboard_page -.->|"authenticates"| node_auth_routes
node_practice_page -.->|"requests"| node_solver_routes
node_scanner_page -.->|"submits"| node_backend_server

click node_main_entry "https://github.com/antony-jacob817/cubora/blob/main/src/main.tsx"
click node_app_routes "https://github.com/antony-jacob817/cubora/blob/main/src/App.tsx"
click node_main_layout "https://github.com/antony-jacob817/cubora/blob/main/src/layouts/MainLayout.tsx"
click node_dashboard_layout "https://github.com/antony-jacob817/cubora/blob/main/src/layouts/DashboardLayout.tsx"
click node_landing_page "https://github.com/antony-jacob817/cubora/blob/main/src/pages/LandingPage.tsx"
click node_dashboard_page "https://github.com/antony-jacob817/cubora/blob/main/src/pages/dashboard/Dashboard.tsx"
click node_practice_page "https://github.com/antony-jacob817/cubora/blob/main/src/pages/practice/PracticeSession.tsx"
click node_scanner_page "https://github.com/antony-jacob817/cubora/blob/main/src/pages/scanner/Scanner.tsx"
click node_analytics_page "https://github.com/antony-jacob817/cubora/blob/main/src/pages/analytics/AnalyticsDashboard.tsx"
click node_coach_page "https://github.com/antony-jacob817/cubora/blob/main/src/pages/coach/AiCoach.tsx"
click node_community_page "https://github.com/antony-jacob817/cubora/blob/main/src/pages/community/CommunityHub.tsx"
click node_multiplayer_page "https://github.com/antony-jacob817/cubora/blob/main/src/pages/multiplayer/MultiplayerHub.tsx"
click node_cube_3d "https://github.com/antony-jacob817/cubora/blob/main/src/components/3d/RubiksCube.tsx"
click node_scanner_pipeline "https://github.com/antony-jacob817/cubora/blob/main/src/services/colorDetector.ts"
click node_cube_logic "https://github.com/antony-jacob817/cubora/blob/main/src/utils/cubing.ts"
click node_solver_ui "https://github.com/antony-jacob817/cubora/blob/main/src/components/solver/PlaybackControls.tsx"
click node_auth_routes "https://github.com/antony-jacob817/cubora/blob/main/cubora-backend/src/routes/authRoutes.js"
click node_solver_routes "https://github.com/antony-jacob817/cubora/blob/main/cubora-backend/src/routes/solverRoutes.js"
click node_auth_middleware "https://github.com/antony-jacob817/cubora/blob/main/cubora-backend/src/middleware/auth.js"
click node_solver_engine "https://github.com/antony-jacob817/cubora/blob/main/cubora-backend/src/services/solverEngine.js"
click node_user_models "https://github.com/antony-jacob817/cubora/blob/main/cubora-backend/src/models/User.js"
click node_db_config "https://github.com/antony-jacob817/cubora/blob/main/cubora-backend/src/config/db.js"
click node_backend_server "https://github.com/antony-jacob817/cubora/blob/main/cubora-backend/src/server.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main_entry,node_app_routes,node_main_layout,node_dashboard_layout,node_landing_page,node_dashboard_page,node_practice_page,node_scanner_page,node_analytics_page,node_coach_page,node_community_page,node_multiplayer_page,node_cube_3d,node_scanner_pipeline,node_cube_logic,node_solver_ui toneBlue
class node_auth_routes,node_solver_routes,node_auth_middleware,node_solver_engine,node_user_models,node_db_config,node_backend_server toneAmber
```

## Components

### Frontend SPA

React + TypeScript Vite application at the repository root.

- [App shell](https://github.com/antony-jacob817/cubora/blob/main/src/main.tsx): entrypoint · Frontend bootstrap and top-level app composition. · `src/main.tsx`
- [Router](https://github.com/antony-jacob817/cubora/blob/main/src/App.tsx): navigation · Route-driven page selection and app framing. · `src/App.tsx`
- [Main layout](https://github.com/antony-jacob817/cubora/blob/main/src/layouts/MainLayout.tsx): layout · Primary site chrome for public and product pages. · `src/layouts/MainLayout.tsx`
- [Dashboard layout](https://github.com/antony-jacob817/cubora/blob/main/src/layouts/DashboardLayout.tsx): layout · Framed layout for authenticated dashboard surfaces. · `src/layouts/DashboardLayout.tsx`
- [Landing](https://github.com/antony-jacob817/cubora/blob/main/src/pages/LandingPage.tsx): page · Public marketing and entry experience. · `src/pages/LandingPage.tsx`
- [Dashboard](https://github.com/antony-jacob817/cubora/blob/main/src/pages/dashboard/Dashboard.tsx): page · Central user hub and navigation gateway. · `src/pages/dashboard/Dashboard.tsx`
- [Practice](https://github.com/antony-jacob817/cubora/blob/main/src/pages/practice/PracticeSession.tsx): page · Solve practice session and timing flow. · `src/pages/practice/PracticeSession.tsx`
- [Scanner](https://github.com/antony-jacob817/cubora/blob/main/src/pages/scanner/Scanner.tsx): page · Camera-based cube scan and correction flow. · `src/pages/scanner/Scanner.tsx`
- [Analytics](https://github.com/antony-jacob817/cubora/blob/main/src/pages/analytics/AnalyticsDashboard.tsx): page · Performance tracking and solve insights. · `src/pages/analytics/AnalyticsDashboard.tsx`
- [AI coach](https://github.com/antony-jacob817/cubora/blob/main/src/pages/coach/AiCoach.tsx): page · Guidance and coaching experience. · `src/pages/coach/AiCoach.tsx`
- [Community](https://github.com/antony-jacob817/cubora/blob/main/src/pages/community/CommunityHub.tsx): page · Social and community hub. · `src/pages/community/CommunityHub.tsx`
- [Multiplayer](https://github.com/antony-jacob817/cubora/blob/main/src/pages/multiplayer/MultiplayerHub.tsx): page · Competitive or collaborative live play hub. · `src/pages/multiplayer/MultiplayerHub.tsx`
- [3D cube](https://github.com/antony-jacob817/cubora/blob/main/src/components/3d/RubiksCube.tsx): visualization · Dedicated Rubik's cube rendering subsystem. · `src/components/3d/RubiksCube.tsx`
- [Vision pipeline](https://github.com/antony-jacob817/cubora/blob/main/src/services/colorDetector.ts): cv pipeline · Camera access, OpenCV loading, and color detection. · `src/services/colorDetector.ts`
- [Cube logic](https://github.com/antony-jacob817/cubora/blob/main/src/utils/cubing.ts): domain utils · Core cube validation and state/move utilities. · `src/utils/cubing.ts`
- [Solver UI](https://github.com/antony-jacob817/cubora/blob/main/src/components/solver/PlaybackControls.tsx): interaction · Playback and solver-oriented UI controls. · `src/components/solver/PlaybackControls.tsx`

### Backend API

Express-style Node server in cubora-backend/.

- [Auth API](https://github.com/antony-jacob817/cubora/blob/main/cubora-backend/src/routes/authRoutes.js): route · Identity and session endpoints. · `cubora-backend/src/routes/authRoutes.js`
- [Solver API](https://github.com/antony-jacob817/cubora/blob/main/cubora-backend/src/routes/solverRoutes.js): route · Solver-related request endpoints. · `cubora-backend/src/routes/solverRoutes.js`
- [Auth guard](https://github.com/antony-jacob817/cubora/blob/main/cubora-backend/src/middleware/auth.js): middleware · Protection for authenticated backend endpoints. · `cubora-backend/src/middleware/auth.js`
- [Solver engine](https://github.com/antony-jacob817/cubora/blob/main/cubora-backend/src/services/solverEngine.js): service · Backend solving and computation layer. · `cubora-backend/src/services/solverEngine.js`
- [User data](https://github.com/antony-jacob817/cubora/blob/main/cubora-backend/src/models/User.js): models · Accounts, settings, solve history, learning, achievements, and scan records. · `cubora-backend/src/models/User.js`
- [Database](https://github.com/antony-jacob817/cubora/blob/main/cubora-backend/src/config/db.js): config · Persistence connection boundary. · `cubora-backend/src/config/db.js`
- [Server](https://github.com/antony-jacob817/cubora/blob/main/cubora-backend/src/server.js): entrypoint · Backend application bootstrap and API composition. · `cubora-backend/src/server.js`

## Connections

- App shell → Router: boots · Frontend entry mounts the application router.
- Router → Main layout: uses · Public pages are framed by the main layout.
- Router → Dashboard layout: uses · Authenticated product areas use the dashboard layout.
- Main layout → Landing: hosts · Main layout renders the landing experience.
- Dashboard layout → Dashboard: hosts · Dashboard layout renders the user hub.
- Dashboard layout → Practice: hosts · Dashboard layout frames practice sessions.
- Dashboard layout → Scanner: hosts · Dashboard layout frames scanning workflows.
- Dashboard layout → Analytics: hosts · Dashboard layout frames analytics views.
- Dashboard layout → AI coach: hosts · Dashboard layout frames coaching features.
- Dashboard layout → Community: hosts · Dashboard layout frames community surfaces.
- Dashboard layout → Multiplayer: hosts · Dashboard layout frames multiplayer features.
- Practice → 3D cube: drives · Practice relies on the cube visualization subsystem.
- Practice → Solver UI: controls · Practice uses playback and solver interaction controls.
- Scanner → Vision pipeline: uses · Scanner page captures video and runs color detection.
- Vision pipeline → Cube logic: normalizes · Detected colors are validated and converted through cube utilities.
- 3D cube → Cube logic: represents · 3D cube state is driven by cube-domain logic.
- Solver UI → 3D cube: plays back · Solver controls animate cube state and moves.
- Auth API → Auth guard: protected by · Authenticated API surface is guarded by middleware.
- Solver API → Solver engine: delegates · Route handlers forward solve work to the engine.
- Auth API → User data: persists · Auth flow reads and writes user-related data.
- Solver API → User data: records · Solver-related operations can store progress and history.
- Server → Auth API: mounts · Server registers authentication routes.
- Server → Solver API: mounts · Server registers solver routes.
- Server → Database: connects · Server initializes the database connection.
- Server → User data: loads · Server runtime depends on persisted domain models.
- Dashboard → Auth API: authenticates · Dashboard interactions can rely on session and identity APIs.
- Practice → Solver API: requests · Practice flow can request solver support from the backend.
- Scanner → Server: submits · Scan results may be sent to backend services for persistence.
