# syed-m-hussain/openrobotics-lab architecture

> Architecture diagram of the GitHub repository syed-m-hussain/openrobotics-lab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/syed-m-hussain/openrobotics-lab
- Repository: https://github.com/syed-m-hussain/openrobotics-lab

## Overview

##### Project type and purpose
- This is a single-page, static frontend application built with React (TypeScript) and Vite.
- Purpose: an open-source robotics learning platform providing tutorials, courses, books, tools, and community projects.

##### File structure
- Top-level artifacts:
- Dockerfile, docker-compose.yml, nginx.conf → containerization & production server
- .github/workflows/preview.yml → CI pipeline for preview builds
- src/ → React code (components/, ui/ library wrappers, pages/, contexts/, hooks/, lib/)
- public/ → static assets (robots.txt, favicon, etc.)
- No server/backend code: purely client code bundled by Vite and served as static files.

##### Key insights from README
- Two deployment modes:
- Dev: Node/Vite server in Docker container (port 8080) with hot-reload
- Prod: Multi-stage Docker build producing static assets served by Nginx (port 80)
- CI: GitHub Actions for preview environments; optional deployment to Vercel via vercel.json

##### Main components
a. Developer workstation & GitHub
- Local source code, Docker Compose dev profile
- GitHub repo with CI workflow (.github/workflows/preview.yml)
b. Continuous Integration / Preview
- GitHub Actions build → deploy preview to ephemeral environment (optional cloud service)
c. Development environment
- Docker Compose “dev” service: Node.js + Vite dev server
- Volume mounts: source code ↔ container
- Exposed port 8080 → browser
d. Production environment
- Docker multi-stage build:
- Stage 1: Node + Vite build → dist/
- Stage 2: Nginx container serves dist/
- Exposed port 80 → end-users’ browsers
e. Client (Browser)
- Consumes static assets, runs React application, makes any API calls (if added later)

##### Relationships & interactions
- Developer commits → pushed to GitHub → triggers CI → optional preview deployment
- For local dev: docker-compose up --profile dev → Vite → browser
- For prod: docker-compose up → Nginx → browser
- Browser ↔ Nginx (HTTP/HTTPS)
- (Future) Browser ↔ external APIs or headless CMS if data moves out of static files

##### Architectural patterns & design principles
- Static Single-Page Application (SPA)
- Containerization for consistency across dev and prod
- Multi-stage Docker builds for optimized image size
- Separation of concerns: build toolchain (Vite) vs runtime server (Nginx)
- CI/CD pipeline for automated preview and production builds

##### Relevant technologies & libraries
- React, React Router v6, React Query (state + data fetching)
- TypeScript, Vite + SWC, Tailwind CSS, shadcn/ui, Lucide React
- Docker, Docker Compose, Nginx, GitHub Actions, (optional) Vercel

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Developer & CI"
        Developer["Developer Workstation"]:::code
        GitHub["GitHub Repo"]:::code
        CI["GitHub Actions CI / Preview Pipeline"]:::ci
        Vercel["(Optional) Vercel Deployment"]:::env
    end

    subgraph "Source Code"
        ViteConfig["Vite Config\nvite.config.ts"]:::code
        ReactEntry["React Entry\nsrc/main.tsx"]:::code
        AppShell["App Shell & Routing\nsrc/App.tsx\nsrc/pages/*"]:::code
        UILib["UI Component Library\nsrc/components/ui/"]:::code
        CoreUI["Core UI Components\nsrc/components/"]:::code
        Utils["Utility Functions\nsrc/lib/utils.ts"]:::code
        Contexts["Application Contexts\nsrc/contexts/ThemeContext.tsx"]:::code
        Hooks["Custom Hooks\nsrc/hooks/"]:::code
        TailwindConfig["Tailwind CSS Config\ntailwind.config.ts"]:::code
        PkgManifest["Dependency Manifests\npackage.json & bun.lockb"]:::code
        PublicAssets["Static Assets\npublic/"]:::artifact
    end

    subgraph "Local Development"
        DevCompose["Docker Compose Dev\n(Node + Vite)"]:::container
        DevContainer["Dev Container\n(Node + Vite Dev Server)"]:::container
    end

    subgraph "Production Deployment"
        ProdBuild["Prod Build Stage\nNode + Vite → dist/"]:::env
        Artifact["Build Artifact\ndist/"]:::artifact
        ProdContainer["Prod Container\nNginx Serving Static Assets"]:::container
    end

    Browser["End User Browser"]:::client

    Developer -->|push code| GitHub
    GitHub -->|triggers| CI
    CI -->|deploy preview| Vercel

    SourceCode -->|mounted by| DevCompose
    DevCompose -->|runs| DevContainer
    DevContainer -->|serves via HTTP| Browser

    SourceCode -->|used in build| ProdBuild
    ProdBuild -->|outputs dist/| Artifact
    Artifact -->|served by| ProdContainer
    ProdContainer -->|serves via HTTP| Browser

    click CI "https://github.com/syed-m-hussain/openrobotics-lab/blob/main/.github/workflows/preview.yml"
    click DevCompose "https://github.com/syed-m-hussain/openrobotics-lab/blob/main/docker-compose.yml"
    click DevContainer "https://github.com/syed-m-hussain/openrobotics-lab/tree/main/Dockerfile"
    click ProdContainer "https://github.com/syed-m-hussain/openrobotics-lab/blob/main/nginx.conf"
    click ViteConfig "https://github.com/syed-m-hussain/openrobotics-lab/blob/main/vite.config.ts"
    click ReactEntry "https://github.com/syed-m-hussain/openrobotics-lab/blob/main/src/main.tsx"
    click AppShell "https://github.com/syed-m-hussain/openrobotics-lab/blob/main/src/App.tsx"
    click UILib "https://github.com/syed-m-hussain/openrobotics-lab/tree/main/src/components/ui/"
    click CoreUI "https://github.com/syed-m-hussain/openrobotics-lab/tree/main/src/components/"
    click Utils "https://github.com/syed-m-hussain/openrobotics-lab/blob/main/src/lib/utils.ts"
    click Contexts "https://github.com/syed-m-hussain/openrobotics-lab/blob/main/src/contexts/ThemeContext.tsx"
    click Hooks "https://github.com/syed-m-hussain/openrobotics-lab/tree/main/src/hooks/"
    click TailwindConfig "https://github.com/syed-m-hussain/openrobotics-lab/blob/main/tailwind.config.ts"
    click PkgManifest "https://github.com/syed-m-hussain/openrobotics-lab/blob/main/package.json"
    click PublicAssets "https://github.com/syed-m-hussain/openrobotics-lab/tree/main/public/"
    click Vercel "https://github.com/syed-m-hussain/openrobotics-lab/blob/main/vercel.json"

    classDef code fill:#E0FFE0,stroke:#006400
    classDef ci fill:#CCFFCC,stroke:#009900
    classDef container fill:#D0E7FF,stroke:#00008B
    classDef env fill:#FFE0B2,stroke:#FF8C00
    classDef client fill:#F2F2F2,stroke:#707070
    classDef artifact fill:#CCCCFF,stroke:#4B0082
```
