# beginnercoder52/asl_website architecture

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

- Interactive diagram: https://gitdiagram.com/beginnercoder52/asl_website
- Repository: https://github.com/beginnercoder52/asl_website

## Overview

##### Project type and purpose
- This is a full-stack web application for real-time American Sign Language (ASL) recognition.
- It consists of three major parts:
- An AI training and model-conversion pipeline (Python/Keras → TensorFlow.js).
- A backend REST API server (Node.js/Express) that hosts the converted model files and exposes inference endpoints (and potentially persists usage data).
- A React-based single-page frontend that captures live video from the user’s camera, calls the backend API for predictions, and displays results.

##### File structure
Top level:
- AI/ – Python scripts, dataset folders (A–Z, 0–9), Keras model, preprocessing and training code, plus a conversion script to TFJS.
- backend/ –
– models/asl_models/ (model.json + weights.bin delivered by convert_to_tfjs.py)
– package.json & requirements.txt (Node and any Python/other deps)
– src/db.js (database connection), src/routes.js (Express routes), src/server.js (HTTP server)
- frontend/ –
– public/index.html
– src/ (React components CameraFeed, PredictionDisplay, App.js, index.js)
– Tailwind CSS config

##### README insights
(Empty in this case – structure speaks for itself.)

a. Offline AI pipeline
- Data preprocessing (preprocess.py)
- Model training (train.py → asl_model.keras)
- Model conversion (convert_to_tfjs.py → model.json + weights.bin)
- Artifact storage (AI/asl_model.keras and AI/data for versioning)
b. Backend services
- Express server (server.js)
- Routing layer (routes.js) – e.g., POST /predict
- Database connector (db.js) – logs, user info, etc.
- Static hosting of TFJS model assets (models/asl_models/)
c. Frontend UI
- CameraFeed component captures frames
- PredictionDisplay shows labels & confidence
- API client inside App.js calls backend → receives JSON prediction
- Tailwind for styling

Relationships & Data flow
1. Offline: raw images → preprocess.py → train.py → Keras model → convert_to_tfjs.py → tfjs artifacts → check into backend/models
2. Runtime:
User Camera → Frontend Component → HTTP Request (/predict) → Backend routes.js → loads TFJS model → runs inference → (optionally logs to DB via db.js) → returns JSON → Frontend updates UI

##### Architectural patterns & principles
- Layered separation:
Presentation (React) ↔ API (Express) ↔ Inference engine (TFJS) ↔ Data store (DB)
- Single Responsibility: each folder handles one concern (AI, backend, frontend).
- Stateless API: inference calls carry image data, server does not maintain session state except via the DB if needed.

##### Relevant technologies
- Python/Keras + TensorFlow for training
- TensorFlow.js for browser/server inference
- Node.js + Express for REST endpoints
- React + Tailwind CSS for SPA frontend
- Any DB (configured in db.js) – e.g., MongoDB or PostgreSQL

##### Summary
- Break the system into AI pipeline, backend API, frontend UI, and datastore.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Offline AI Pipeline"
        DP["Data Preprocessing\n(preprocess.py)"]:::ai
        TR["Model Training\n(train.py)"]:::ai
        CV["Model Conversion\n(convert_to_tfjs.py)"]:::ai
        ARC["Keras Model Artifact\n(asl_model.keras)"]:::artifact
        RAW["Raw Dataset\n(data/DATASET/)"]:::data
    end

    subgraph "Backend Service"
        SERV["Express Server\n(server.js)"]:::backend
        ROUTES["Routing Layer\n(routes.js)"]:::backend
        DB["Database Connector\n(db.js)"]:::db
        SERVMODELS["TFJS Models\n(model.json & weights.bin)"]:::artifact
        PKG["package.json"]:::config
        REQ["requirements.txt"]:::config
    end

    subgraph "Frontend UI"
        HTML["HTML Host Page\n(index.html)"]:::frontend
        IDX["React Entry Point\n(index.js)"]:::frontend
        APP["Main App Component\n(App.js)"]:::frontend
        CF["CameraFeed Component\n(CameraFeed.js)"]:::frontend
        PD["PredictionDisplay Component\n(PredictionDisplay.js)"]:::frontend
        APPCSS["App Styling\n(App.css)"]:::config
        CFG["Tailwind Config\n(tailwind.config.js)"]:::config
        PKGFE["package.json"]:::config
        PKGFE2["package-lock.json"]:::config
    end

    README["README.md"]:::doc

    %% Offline AI Pipeline flow
    RAW -->|"raw images"| DP
    DP -->|"cleaned images"| TR
    TR -->|"asl_model.keras"| ARC
    ARC -->|"converted to TFJS"| CV
    CV -->|"tfjs artifacts"| SERVMODELS

    %% Backend relationships
    SERV -->|"uses routing"| ROUTES
    SERV -->|"serves static assets"| SERVMODELS
    ROUTES -->|"loads model"| SERVMODELS
    ROUTES -->|"logs usage"| DB
    SERV --> PKG
    SERV --> REQ

    %% Frontend relationships
    HTML --> IDX
    IDX --> APP
    APP --> CF
    APP --> PD
    CF -->|"video frames"| APP
    PD -->|"displays predictions"| APP
    APP -->|"POST /predict"| SERV
    SERV -->|"JSON prediction"| APP
    APP --> APPCSS
    APP --> CFG
    APP --> PKGFE
    APP --> PKGFE2

    %% Documentation link
    README --> RAW
    README --> SERV
    README --> HTML

    %% Click Events
    click DP "https://github.com/beginnercoder52/asl_website/blob/main/AI/data/preprocess.py"
    click TR "https://github.com/beginnercoder52/asl_website/blob/main/AI/train.py"
    click CV "https://github.com/beginnercoder52/asl_website/blob/main/AI/convert_to_tfjs.py"
    click ARC "https://github.com/beginnercoder52/asl_website/blob/main/AI/asl_model.keras"
    click RAW "https://github.com/beginnercoder52/asl_website/tree/main/AI/data/DATASET/"
    click SERV "https://github.com/beginnercoder52/asl_website/blob/main/backend/src/server.js"
    click ROUTES "https://github.com/beginnercoder52/asl_website/blob/main/backend/src/routes.js"
    click DB "https://github.com/beginnercoder52/asl_website/blob/main/backend/src/db.js"
    click SERVMODELS "https://github.com/beginnercoder52/asl_website/tree/main/backend/models/asl_models/"
    click PKG "https://github.com/beginnercoder52/asl_website/blob/main/backend/package.json"
    click REQ "https://github.com/beginnercoder52/asl_website/blob/main/backend/requirements.txt"
    click HTML "https://github.com/beginnercoder52/asl_website/blob/main/frontend/public/index.html"
    click IDX "https://github.com/beginnercoder52/asl_website/blob/main/frontend/src/index.js"
    click APP "https://github.com/beginnercoder52/asl_website/blob/main/frontend/src/App.js"
    click CF "https://github.com/beginnercoder52/asl_website/blob/main/frontend/src/components/CameraFeed.js"
    click PD "https://github.com/beginnercoder52/asl_website/blob/main/frontend/src/components/PredictionDisplay.js"
    click APPCSS "https://github.com/beginnercoder52/asl_website/blob/main/frontend/src/App.css"
    click CFG "https://github.com/beginnercoder52/asl_website/blob/main/frontend/tailwind.config.js"
    click PKGFE "https://github.com/beginnercoder52/asl_website/blob/main/frontend/package.json"
    click PKGFE2 "https://github.com/beginnercoder52/asl_website/blob/main/frontend/package-lock.json"
    click README "https://github.com/beginnercoder52/asl_website/blob/main/README.md"

    %% Styles
    classDef ai fill:#D6EFFF,stroke:#1E70BF;
    classDef backend fill:#E2FFD4,stroke:#4CAF50;
    classDef frontend fill:#FFE4D6,stroke:#FF8C00;
    classDef data fill:#FFF4D6,stroke:#D2A106;
    classDef artifact fill:#F0E6FF,stroke:#9C27B0;
    classDef db fill:#CDE4FF,stroke:#1565C0;
    classDef config fill:#F5F5F5,stroke:#888888;
    classDef doc fill:#EEEEEE,stroke:#666666;
```
