# cmcecora/aipad architecture

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

- Interactive diagram: https://gitdiagram.com/cmcecora/aipad
- Repository: https://github.com/cmcecora/aipad

## Overview

##### Project type and purpose
- This is a full-stack mobile/web application built on Expo (React Native + web via expo-router) with a lightweight Node.js “sync” backend.
- Purpose: record tennis match videos, detect and analyze court lines, produce analytics and reports, and synchronize recordings via a central sync server.

##### File structure
Top-level:
- app/           – Expo Router pages and layout for tabs (analytics, matches, settings, calibration, record, upload, video-player, etc.)
- components/    – Reusable React Native UI components and domain‐specific engines (AIAnalysisEngine, RaydelRatingEngine, SyncManager, VideoRecorder).
- hooks/         – Custom React hooks (useFrameworkReady, useVideoRecording).
- utils/         – Pure utility modules for video processing and court-line detection.
- assets/        – Static images.
- server/        – Node.js sync server (sync-server.js), with its own package.json and README.
- config files  – .env.example, tsconfig.json, app.json, .prettierrc, etc.

##### README insights
- Front-end is an Expo project; run with npm run dev, supports iOS/Android/web.
- Uses expo-router for filesystem-based routing.
- Server is a standalone Node.js process for synchronizing recordings (no mention of a DB, so likely file-based or in-memory).

a. Main components
1. Mobile/Web Client (Expo App)
– UI Layers: Tabs (Matches, Analytics, Settings)
– VideoRecorder component
– SyncManager component
– AIAnalysisEngine & RaydelRatingEngine (client-side processing)
2. Sync Server (Node.js)
– HTTP/WS endpoints to receive and serve video assets
3. (Optional) Storage layer
– File system or S3 bucket behind the sync server (if extended)
4. External services
– Expo Go / Device Simulators

b. Relationships & interactions
1. User interacts with Expo App UI → triggers VideoRecorder
2. VideoRecorder produces raw video data → passed to SyncManager
3. SyncManager sends video data over HTTP/WS to Sync Server
4. Sync Server stores video and returns acknowledgement or URL
5. Upon storage, AIAnalysisEngine & RaydelRatingEngine analyze the video locally or fetch data back from server
6. Results flow back into the UI (Analytics page)
7. Utilities (courtLineDetector, videoUtils) are invoked by analysis engines

c. Architectural patterns & principles
– Separation of concerns: UI vs recording vs sync vs analysis
– Filesystem-based routing (expo-router) for the client
– Modular engines (AIAnalysisEngine, RaydelRatingEngine) encapsulate domain logic
– Thin synchronization service (microservice style)

d. Key technologies/frameworks
– Expo (React Native + web) with expo-router
– React Hooks & TypeScript
– Node.js sync server (Express or built-in HTTP)
– Custom computer-vision modules in utils/components

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User"]:::actor

    %% Client Layer
    subgraph "Expo Client (Mobile/Web)" 
        direction TB
        subgraph "UI Layer" 
            direction TB
            TabsLayout["Tabs Layout\n(Analytics, Matches, Settings)"]:::ui
            AnalyticsPage["Analytics Page"]:::ui
            MatchesPage["Matches Page"]:::ui
            SettingsPage["Settings Page"]:::ui
            RecordPage["Record Page"]:::ui
            RecordingStatePage["Recording State Page"]:::ui
            VideoPlayerPage["Video Player Page"]:::ui
            UploadPage["Upload Page"]:::ui
            SyncRecordingPages["Sync Recording Pages"]:::ui
            ReportDetailPage["Report Detail Page"]:::ui
        end
        subgraph "Components" 
            direction TB
            VideoRecorder["VideoRecorder Component"]:::component
            SyncManager["SyncManager Component"]:::component
            AIAnalysisEngine["AIAnalysisEngine Module"]:::service
            RaydelRatingEngine["RaydelRatingEngine Module"]:::service
        end
        subgraph "Hooks" 
            direction TB
            FrameworkReadyHook["useFrameworkReady Hook"]:::hook
            VideoRecordingHook["useVideoRecording Hook"]:::hook
        end
        subgraph "Utilities" 
            direction TB
            CourtLineDetector["Court Line Detector Utility"]:::util
            VideoUtils["Video Processing Utilities"]:::util
        end
    end

    %% Server Layer
    subgraph "Sync Server (Node.js Backend)" 
        direction TB
        SyncServer["sync-server.js\n(Express HTTP/WS)"]:::backend
        ServerConfig["package.json\nREADME.md"]:::backend
    end

    %% Assets & Config
    subgraph "Project Config & Assets"
        direction TB
        EnvExample[".env.example"]:::config
        ProjectConfig["tsconfig.json\napp.json\n.prettierrc"]:::config
        Assets["Static Assets (images/)"]:::assets
    end

    %% Interactions
    User -->|"interacts with"| TabsLayout
    TabsLayout -->|"navigates to"| RecordPage
    RecordPage -->|"starts recording"| VideoRecorder
    VideoRecorder -->|"video data"| SyncManager
    SyncManager -->|"HTTP/WS upload"| SyncServer
    SyncServer -->|"acknowledgement/URL"| SyncManager
    SyncManager -->|"passes URL"| AIAnalysisEngine
    SyncManager -->|"passes URL"| RaydelRatingEngine
    AIAnalysisEngine -->|"analysis results"| AnalyticsPage
    RaydelRatingEngine -->|"rating results"| AnalyticsPage
    AIAnalysisEngine --> CourtLineDetector
    AIAnalysisEngine --> VideoUtils
    RaydelRatingEngine --> VideoUtils

    %% Click Events - UI
    click TabsLayout "https://github.com/cmcecora/aipad/blob/main/app/(tabs)/_layout.tsx"
    click AnalyticsPage "https://github.com/cmcecora/aipad/blob/main/app/(tabs)/analytics.tsx"
    click MatchesPage "https://github.com/cmcecora/aipad/blob/main/app/(tabs)/matches.tsx"
    click SettingsPage "https://github.com/cmcecora/aipad/blob/main/app/(tabs)/settings.tsx"
    click RecordPage "https://github.com/cmcecora/aipad/blob/main/app/record.tsx"
    click RecordingStatePage "https://github.com/cmcecora/aipad/blob/main/app/recording.tsx"
    click VideoPlayerPage "https://github.com/cmcecora/aipad/blob/main/app/video-player.tsx"
    click UploadPage "https://github.com/cmcecora/aipad/blob/main/app/upload.tsx"
    click SyncRecordingPages "https://github.com/cmcecora/aipad/blob/main/app/sync-recording.tsx"
    click SyncRecordingPages "https://github.com/cmcecora/aipad/blob/main/app/sync-recording-old.tsx"
    click ReportDetailPage "https://github.com/cmcecora/aipad/blob/main/app/report/[id].tsx"

    %% Click Events - Components
    click VideoRecorder "https://github.com/cmcecora/aipad/blob/main/components/VideoRecorder.tsx"
    click SyncManager "https://github.com/cmcecora/aipad/blob/main/components/SyncManager.ts"
    click AIAnalysisEngine "https://github.com/cmcecora/aipad/blob/main/components/AIAnalysisEngine.ts"
    click RaydelRatingEngine "https://github.com/cmcecora/aipad/blob/main/components/RaydelRatingEngine.ts"

    %% Click Events - Hooks
    click FrameworkReadyHook "https://github.com/cmcecora/aipad/blob/main/hooks/useFrameworkReady.ts"
    click VideoRecordingHook "https://github.com/cmcecora/aipad/blob/main/hooks/useVideoRecording.ts"

    %% Click Events - Utilities
    click CourtLineDetector "https://github.com/cmcecora/aipad/blob/main/utils/courtLineDetector.ts"
    click VideoUtils "https://github.com/cmcecora/aipad/blob/main/utils/videoUtils.ts"

    %% Click Events - Server
    click SyncServer "https://github.com/cmcecora/aipad/blob/main/server/sync-server.js"
    click ServerConfig "https://github.com/cmcecora/aipad/blob/main/server/package.json"
    click ServerConfig "https://github.com/cmcecora/aipad/blob/main/server/README.md"

    %% Click Events - Config & Assets
    click EnvExample "https://github.com/cmcecora/aipad/blob/main/.env.example"
    click ProjectConfig "https://github.com/cmcecora/aipad/blob/main/tsconfig.json"
    click Assets "https://github.com/cmcecora/aipad/tree/main/assets/images/"

    %% Styles
    classDef actor fill:#f9f,stroke:#333,stroke-width:1px
    classDef ui fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
    classDef component fill:#c8e6c9,stroke:#388e3c,stroke-width:1px
    classDef service fill:#a5d6a7,stroke:#2e7d32,stroke-width:1px
    classDef hook fill:#ffe082,stroke:#ff8f00,stroke-width:1px
    classDef util fill:#e0e0e0,stroke:#616161,stroke-width:1px
    classDef backend fill:#ffcc80,stroke:#ef6c00,stroke-width:1px
    classDef config fill:#d1c4e9,stroke:#673ab7,stroke-width:1px
    classDef assets fill:#f0f4c3,stroke:#827717,stroke-width:1px
```
