# ikrambagban/itranscoder architecture

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

- Interactive diagram: https://gitdiagram.com/ikrambagban/itranscoder
- Repository: https://github.com/ikrambagban/itranscoder

## Overview

##### Project type and purpose
- This is a full-stack, multi-deployment pipeline monorepo. It includes:
- A React web frontend for file upload and progress tracking (apps/web)
- A Node.js “backend” API service (apps/backend) that accepts uploads, schedules jobs, and reports status
- A containerized worker service (apps/container) that executes processing jobs in Docker
- A serverless AWS CDK stack and Lambda functions (apps/serverless) for infra provisioning and/or alternative job execution
- Shared libraries and utilities (packages/cloud-services-manager, packages/ui, etc.) to manage ECS, queues, Redis, UI components, configs
- CI/CD pipelines and Dockerfiles for building and deploying all components

##### File structure
- Top-level “apps” folder holds each deployable service: web, backend, container, serverless
- “packages” holds cross-cutting libraries: cloud-services-manager (ECS/Queue/Redis), UI components, ESLint/TS configs
- Dockerfiles and GitHub Actions workflows define container builds and deployment steps
- Mono-repo orchestrated by pnpm workspaces and Turborepo (pnpm-workspace.yaml, turbo.json)

##### Main components
A. **User & Browser (Frontend)**
- React SPA (apps/web)
- Responsible for file selection, upload, and polling for status
B. **API Service (Backend)**
- Node.js REST API (apps/backend)
- Endpoints: upload, status, control
- Uses helper modules for Docker orchestration and retry logic
C. **Processing Worker (Container Service)**
- Docker image (apps/container)
- Runs jobs scheduled by the backend
- Reports results/status back (e.g., via a message queue or Redis)
D. **Serverless Infra / Lambda**
- AWS CDK Stack (apps/serverless/lib/serverless-stack.ts)
- Lambda functions (apps/serverless/lambda) for optional or alternative task execution
- Might serve as a fallback or for asynchronous event handling (e.g., S3 triggers)
E. **Shared Infrastructure Services**
- Message queue (e.g., SQS or RabbitMQ), Redis cache
- ECS cluster (for Docker tasks)
- S3 or object storage (if relevant for storing uploaded files)
F. **Shared Libraries**
- cloud-services-manager (manages ECS tasks, queues, Redis)
- ui package for consistent styling / components

##### Relationships and data flows
1. User → Frontend: initiates file upload
2. Frontend → Backend API: POST /upload
3. Backend → cloud-services-manager → Queue or ECS: enqueue or launch container task
4. Container Worker (Docker) → processes file → writes status to Redis or sends messages to queue
5. Backend polls Redis or subscribes to queue → updates internal job status
6. Frontend polls Backend: GET /status → renders progress bar or final result
7. (Optional) Lambda functions handle asynchronous events (e.g., file processed notifications)

##### Architectural patterns and design principles
- **Microservices / Modularization**: each deployable resides in its own directory and Dockerfile or CDK stack
- **Polyglot Deployment Options**: container-based vs. serverless
- **Shared Libraries**: avoid code duplication via pnpm workspaces
- **CI/CD Driven**: GitHub Actions workflows build and deploy each component independently
- **Infrastructure as Code**: AWS CDK defines serverless stack

##### Elements
- User-facing components (blue)
- Compute services (green)
- Infrastructure (orange)
- Shared libraries/config (gray)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        User["User & Browser"]:::user
        Frontend["React SPA (apps/web)"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        Backend["Node.js REST API (apps/backend)"]:::compute
    end

    %% Worker Layer
    subgraph "Worker Layer"
        direction TB
        ContainerWorker["ECS Task: apps/container"]:::compute
    end

    %% Serverless Layer
    subgraph "Serverless Layer"
        direction TB
        Serverless["Lambda Functions (apps/serverless)"]:::compute
    end

    %% Infrastructure
    subgraph "Infrastructure Services"
        direction TB
        Queue["Message Queue (SQS/RabbitMQ)"]:::infra
        Redis["Redis Cache"]:::infra
        ECS["ECS Cluster"]:::infra
        S3["Object Storage (S3)"]:::infra
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        direction TB
        CloudLib["cloud-services-manager"]:::shared
        UILib["ui components"]:::shared
    end

    %% CI/CD
    subgraph "CI/CD & Docker"
        direction TB
        WorkflowFrontend["deploy-frontend.yml"]:::cicd
        WorkflowBackend["deploy-backend.yml"]:::cicd
        WorkflowContainer["deploy-container.yml"]:::cicd
        WorkflowServerless["deploy-serverless.yml"]:::cicd
        DockerBackend["Dockerfile.backend"]:::cicd
        DockerContainerFile["Dockerfile.container"]:::cicd
    end

    %% Connections
    User -->|"Uses App"| Frontend
    Frontend -->|"POST /upload<br/>GET /status"| Backend
    Backend -->|"Uses APIs"| CloudLib
    CloudLib -->|"Launch Task"| ECS
    Backend -->|"Enqueue Job"| Queue
    ContainerWorker -->|"Process File"| S3
    ContainerWorker -->|"Publish Status"| Redis
    ContainerWorker -->|"Send Message"| Queue
    Queue -->|"Job Updates"| Backend
    Backend -->|"Poll Status"| Redis
    Serverless -->|"Handle Events"| Queue
    Serverless -->|"Optional Processing"| S3
    Backend -->|"Read/Write Storage"| S3
    Backend -->|"Read/Write Cache"| Redis
    Frontend -->|"Use UI Components"| UILib

    %% CI/CD connections
    WorkflowFrontend --> Frontend
    WorkflowBackend --> Backend
    WorkflowContainer --> ContainerWorker
    WorkflowServerless --> Serverless
    DockerBackend --> Backend
    DockerContainerFile --> ContainerWorker

    %% Click Events
    click Frontend "https://github.com/ikrambagban/itranscoder/tree/main/apps/web"
    click Backend "https://github.com/ikrambagban/itranscoder/blob/main/apps/backend/src/index.ts"
    click ContainerWorker "https://github.com/ikrambagban/itranscoder/blob/main/apps/container/src/index.ts"
    click Serverless "https://github.com/ikrambagban/itranscoder/blob/main/apps/serverless/lib/serverless-stack.ts"
    click CloudLib "https://github.com/ikrambagban/itranscoder/blob/main/packages/cloud-services-manager/src/ecs-manager.ts"
    click UILib "https://github.com/ikrambagban/itranscoder/blob/main/packages/ui/src/components/button.tsx"
    click WorkflowFrontend "https://github.com/ikrambagban/itranscoder/blob/main/.github/workflows/deploy-frontend.yml"
    click WorkflowBackend "https://github.com/ikrambagban/itranscoder/blob/main/.github/workflows/deploy-backend.yml"
    click WorkflowContainer "https://github.com/ikrambagban/itranscoder/blob/main/.github/workflows/deploy-container.yml"
    click WorkflowServerless "https://github.com/ikrambagban/itranscoder/blob/main/.github/workflows/deploy-serverless.yml"
    click DockerBackend "https://github.com/ikrambagban/itranscoder/blob/main/docker/Dockerfile.backend"
    click DockerContainerFile "https://github.com/ikrambagban/itranscoder/blob/main/docker/Dockerfile.container"

    %% Styles
    classDef user fill:#DCEEFB,stroke:#0366d6,color:#0366d6;
    classDef frontend fill:#B6E0FE,stroke:#1c7ed6,color:#1c7ed6;
    classDef compute fill:#ADE8F4,stroke:#15aabf,color:#15aabf;
    classDef infra fill:#FFD8A8,stroke:#f76707,color:#f76707;
    classDef shared fill:#E0E0E0,stroke:#495057,color:#495057;
    classDef cicd fill:#EAD7FF,stroke:#845ef7,color:#845ef7;
```
