How antony-jacob817/cubora works
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: DashboardLayout.tsx Dashboard layout · server.js Server · PracticeSession.tsx Practice · authRoutes.js Auth API
Components 23
Frontend SPA
React + TypeScript Vite application at the repository root.
- App shell · Frontend bootstrap and top-level app composition.
src/main.tsx - Router · Route-driven page selection and app framing.
src/App.tsx - Main layout · Primary site chrome for public and product pages.
src/layouts/MainLayout.tsx - Dashboard layout · Framed layout for authenticated dashboard surfaces.
src/layouts/DashboardLayout.tsx - Landing · Public marketing and entry experience.
src/pages/LandingPage.tsx - Dashboard · Central user hub and navigation gateway.
src/pages/dashboard/Dashboard.tsx - Practice · Solve practice session and timing flow.
src/pages/practice/PracticeSession.tsx - Scanner · Camera-based cube scan and correction flow.
src/pages/scanner/Scanner.tsx - Analytics · Performance tracking and solve insights.
src/pages/analytics/AnalyticsDashboard.tsx - AI coach · Guidance and coaching experience.
src/pages/coach/AiCoach.tsx - Community · Social and community hub.
src/pages/community/CommunityHub.tsx - Multiplayer · Competitive or collaborative live play hub.
src/pages/multiplayer/MultiplayerHub.tsx - 3D cube · Dedicated Rubik's cube rendering subsystem.
src/components/3d/RubiksCube.tsx - Vision pipeline · Camera access, OpenCV loading, and color detection.
src/services/colorDetector.ts - Cube logic · Core cube validation and state/move utilities.
src/utils/cubing.ts - Solver UI · Playback and solver-oriented UI controls.
src/components/solver/PlaybackControls.tsx
Backend API
Express-style Node server in cubora-backend/.
- Auth API · Identity and session endpoints.
cubora-backend/src/routes/authRoutes.js - Solver API · Solver-related request endpoints.
cubora-backend/src/routes/solverRoutes.js - Auth guard · Protection for authenticated backend endpoints.
cubora-backend/src/middleware/auth.js - Solver engine · Backend solving and computation layer.
cubora-backend/src/services/solverEngine.js - User data · Accounts, settings, solve history, learning, achievements, and scan records.
cubora-backend/src/models/User.js - Database · Persistence connection boundary.
cubora-backend/src/config/db.js - Server · Backend application bootstrap and API composition.
cubora-backend/src/server.js
Connections 28
- 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.