# fyp-hyz-mjj-2024/posture-video-stream architecture

> Architecture diagram of the GitHub repository fyp-hyz-mjj-2024/posture-video-stream, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fyp-hyz-mjj-2024/posture-video-stream
- Repository: https://github.com/fyp-hyz-mjj-2024/posture-video-stream

## Overview

##### Project Type and Purpose
- This is a full-stack, browser-based frontend application built with Next.js and React, accompanied by a simple Node.js WebSocket server.
- Purpose: Provide a user interface for “Pedestrian Cell Phone Usage Detection” (alias “You Focus Your Walk”), enabling users to register, log in, manage users/faces, upload face data, and perform real-time face comparison via WebSocket.

##### Main Architectural Components
a. Browser / Client
- React components under `components/` (e.g., Indicator.tsx, Inputs.tsx, ListItem.tsx, buttons.tsx)
- Pages under `pages/` (e.g., `pages/index.tsx`, `pages/user/*.tsx`, `pages/face/*.tsx`, `_app.tsx`, `_document.tsx`)
b. Next.js Server (SSR & API)
- Custom server logic in `lib/server.ts`
- API routes under `pages/api/` (e.g., `hello.ts`)
c. WebSocket Server
- `public/ws-server.js` serving real-time face comparison messages on port 8976
d. Shared Utilities & Configuration
- Auth helpers: `lib/auth.ts`
- File handling: `lib/files.ts`
- Common utils: `lib/utils.ts` and `data/WSCode.tsx`
- Environment/config: `.env*`, `next.config.mjs`, `tsconfig.json`, `postcss.config.mjs`, `tailwind.config.ts`
e. Deployment Artefacts
- `Dockerfile` for containerized build and run
- `package.json` / `package-lock.json`, `.eslintrc.json`, `.gitignore`

##### Relationships and Data Flows
- User’s Browser ⟷ Next.js Server over HTTP/HTTPS
- Server-Side Rendering of React pages
- RESTful calls to API routes (e.g., user login/register)
- Browser ⟷ WebSocket Server on `ws://<host>:8976`
- Real-time messages for face comparison sessions
- Next.js Server may interact with file storage or authentication backends via `lib/files.ts` & `lib/auth.ts`

##### Architectural Patterns & Design Principles
- Component-based UI (React)
- MVC-style separation:
- Views → `pages/` & `components/`
- Controllers/Endpoints → `pages/api/`, `public/ws-server.js`
- Models/Services → `lib/*.ts`
- Configuration as code (env files, Next.js config, Dockerfile)
- Concurrency orchestration via `concurrently` (npm scripts)

##### Essential File Names to Display
- UI Layer: `pages/index.tsx`, `pages/user/login.tsx`, `pages/face/compare_face.tsx`, `components/Indicator.tsx`
- API Layer: `pages/api/hello.ts`, `lib/server.ts`
- Realtime Layer: `public/ws-server.js`
- Shared Logic: `lib/auth.ts`, `lib/files.ts`, `lib/utils.ts`
- Config & Deploy: `.env`, `next.config.mjs`, `Dockerfile`

## Diagram (Mermaid)

```mermaid
graph TD
    %% Browser / Client Layer
    subgraph "Browser / Client" 
        direction TB
        ComponentsDir["React UI Components\ncomponents/*"]:::frontend
        IndexPage["Landing Page\npages/index.tsx"]:::frontend
        LoginPage["User Login Page\npages/user/login.tsx"]:::frontend
        RegisterPage["User Registration Page\npages/user/register.tsx"]:::frontend
        ManageUsersPage["User Management Page\npages/user/manage_users.tsx"]:::frontend
        CompareFacePage["Face Compare Page\npages/face/compare_face.tsx"]:::frontend
        UploadFacePage["Face Upload Page\npages/face/upload_face.tsx"]:::frontend
        ManageFacesPage["Face Management Page\npages/face/manage_faces.tsx"]:::frontend
        AppWrapper["Next.js App Wrapper\npages/_app.tsx"]:::frontend
        DocumentTemplate["Custom Document Template\npages/_document.tsx"]:::frontend
    end

    %% Next.js Server Layer
    subgraph "Next.js Server (HTTP 3000)" 
        direction TB
        NextServer["Custom Server & SSR\nlib/server.ts"]:::server
        APIRoutesDir["API Routes Directory\npages/api/"]:::server
        HelloAPI["Example API Endpoint\npages/api/hello.ts"]:::server
    end

    %% WebSocket Server Layer
    subgraph "WebSocket Server (WS 8976)"
        direction TB
        WSServer["Real-time Face Comparison\npublic/ws-server.js"]:::realtime
    end

    %% Shared Utilities Layer
    subgraph "Shared Utilities"
        direction TB
        AuthUtil["Authentication Utilities\nlib/auth.ts"]:::util
        FilesUtil["File Handling Utilities\nlib/files.ts"]:::util
        UtilsUtil["Common Utility Functions\nlib/utils.ts"]:::util
        WSCode["WebSocket Message Codes\ndata/WSCode.tsx"]:::util
    end

    %% Configuration & Deployment Layer
    subgraph "Config & Deployment"
        direction TB
        EnvFiles["Environment Configuration\n.env, .env.development, .env.production"]:::config
        NextConfig["Next.js Configuration\nnext.config.mjs"]:::config
        TSConfig["TypeScript Configuration\ntsconfig.json"]:::config
        TailwindConfig["Tailwind CSS Configuration\ntailwind.config.ts"]:::config
        PostCSSConfig["PostCSS Configuration\npostcss.config.mjs"]:::config
        DockerfileNode["Dockerfile for Deployment\nDockerfile"]:::config
    end

    %% Connections
    ComponentsDir -->|HTTP/HTTPS| NextServer
    IndexPage -->|HTTP/HTTPS| NextServer
    LoginPage -->|HTTP/HTTPS| NextServer
    RegisterPage -->|HTTP/HTTPS| NextServer
    ManageUsersPage -->|HTTP/HTTPS| NextServer
    CompareFacePage -->|HTTP/HTTPS| NextServer
    UploadFacePage -->|HTTP/HTTPS| NextServer
    ManageFacesPage -->|HTTP/HTTPS| NextServer
    AppWrapper -->|HTTP/HTTPS| NextServer
    DocumentTemplate -->|HTTP/HTTPS| NextServer

    ComponentsDir -->|WebSocket| WSServer
    CompareFacePage -->|WebSocket| WSServer

    NextServer -->|uses| AuthUtil
    NextServer -->|uses| FilesUtil
    NextServer -->|uses| UtilsUtil

    APIRoutesDir -->|contains| HelloAPI

    %% Click Events
    click ComponentsDir "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/tree/master/components/"
    click IndexPage "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/blob/master/pages/index.tsx"
    click LoginPage "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/blob/master/pages/user/login.tsx"
    click RegisterPage "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/blob/master/pages/user/register.tsx"
    click ManageUsersPage "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/blob/master/pages/user/manage_users.tsx"
    click CompareFacePage "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/blob/master/pages/face/compare_face.tsx"
    click UploadFacePage "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/blob/master/pages/face/upload_face.tsx"
    click ManageFacesPage "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/blob/master/pages/face/manage_faces.tsx"
    click AppWrapper "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/blob/master/pages/_app.tsx"
    click DocumentTemplate "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/blob/master/pages/_document.tsx"
    click NextServer "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/blob/master/lib/server.ts"
    click APIRoutesDir "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/tree/master/pages/api/"
    click HelloAPI "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/blob/master/pages/api/hello.ts"
    click WSServer "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/blob/master/public/ws-server.js"
    click AuthUtil "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/blob/master/lib/auth.ts"
    click FilesUtil "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/blob/master/lib/files.ts"
    click UtilsUtil "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/blob/master/lib/utils.ts"
    click WSCode "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/blob/master/data/WSCode.tsx"
    click EnvFiles "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/blob/master/.env"
    click NextConfig "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/blob/master/next.config.mjs"
    click TSConfig "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/blob/master/tsconfig.json"
    click TailwindConfig "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/blob/master/tailwind.config.ts"
    click PostCSSConfig "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/blob/master/postcss.config.mjs"
    click DockerfileNode "https://github.com/fyp-hyz-mjj-2024/posture-video-stream/tree/master/Dockerfile"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#1f78b4,color:#000;
    classDef server fill:#d4edda,stroke:#2e7d32,color:#000;
    classDef realtime fill:#ffe5b4,stroke:#f57c00,color:#000;
    classDef util fill:#e2e3e5,stroke:#6c757d,color:#000;
    classDef config fill:#f8f9fa,stroke:#343a40,color:#000;
```
