# bleedingdev/coursition-effect.experiment architecture

> Architecture diagram of the GitHub repository bleedingdev/coursition-effect.experiment, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bleedingdev/coursition-effect.experiment
- Repository: https://github.com/bleedingdev/coursition-effect.experiment

## Overview

##### Project Type and Purpose
- This is a single-service, backend media-parsing API built in TypeScript using Effect-TS patterns.
- It exposes HTTP endpoints for submitting media for parsing and fetching job status/results.

##### File Structure
- Top-level entrypoints:
- server.ts – HTTP server bootstrap
- api.ts / client.ts – shared API definitions and client logic
- config.ts – configuration management
- Core modules under src/:
- domain/ – schema & domain models (jobs, media, common)
- stores/ – data access for jobs & media
- usecases/ – business logic for jobs & media workflows
- handlers/ – HTTP request handlers per endpoint (jobs/, media/)
- platform/ – external-service adapters (S3 FS)
- steps/ – task steps (download link, transcribe, persist subtitles)
- Testing in each layer (vitest) ensures separation of concerns.

##### README Insights
- Confirms a layered architecture: stores → usecases → handlers.
- Lists external config (DB table, S3, logging, ports).
- Describes API surface:
- POST /media/parse
- GET /media/jobs
- GET /media/job/{id}
- GET /media/job/{id}/result

##### Main Components and Their Interactions
a. Client Layer
- “client.ts” (could be browser or CLI) sends HTTP requests to the server.
b. API / HTTP Server
- server.ts hosts handlers on an HTTP port (3001 by default).
- api.ts defines endpoint schemas and routes.
c. Handler Layer
- Handlers accept HTTP requests, map to usecase inputs, and return HTTP responses.
- Organized into jobs/ and media/ subfolders.
d. Usecase (Business Logic) Layer
- Orchestrates domain logic and side-effects.
- Jobs usecases: get-jobs, get-job-by-id, get-job-result.
- Media usecase: transcribe-workflow (invokes steps in sequence).
e. Steps / Workflow Engine
- Atomic tasks under src/steps/media (download, transcribe, persist).
- Invoked by usecases to perform the media parsing pipeline.
f. Store (Data Access) Layer
- jobs.store and media.store implement CRUD against a persistent store (e.g., DynamoDB table, configured via JOBS_TABLE).
g. Domain Models
- Schemas and typed errors ensure type-safe data flow across layers.
h. Platform Adapters
- s3-fs.ts abstracts AWS S3 or filesystem operations for media blobs.
i. External Services
- Persistent data store (DB table)
- S3 bucket or equivalent object storage

##### Architectural Patterns & Principles
- Layered Separation: clear boundaries between HTTP, business logic, and data access.
- Functional Effects: side-effects modelled with Effect-TS for error handling and composability.
- Domain-Driven Design: domain folder with schemas, errors, and business rules.
- Dependency Injection via config.ts for environment-based settings.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["API Client"]:::api
    click Client "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/client.ts"

    %% API / HTTP Server
    Server["HTTP Server"]:::api
    click Server "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/server.ts"
    API["API Schemas & Routes"]:::api
    click API "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/api.ts"
    Config["Configuration"]:::config
    click Config "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/config.ts"

    %% Handler Layer
    subgraph "Handlers"
        direction TB
        GetJobs["Get All Jobs Handler"]:::api
        click GetJobs "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/handlers/jobs/get-jobs.handler.ts"
        GetJobById["Get Job By ID Handler"]:::api
        click GetJobById "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/handlers/jobs/get-job-by-id.handler.ts"
        GetJobResult["Get Job Result Handler"]:::api
        click GetJobResult "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/handlers/jobs/get-job-result.handler.ts"
        TranscribeHandler["Media Transcribe Workflow Handler"]:::api
        click TranscribeHandler "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/handlers/media/transcribe-workflow.handler.ts"
    end

    %% Usecase Layer
    subgraph "Usecases"
        direction TB
        GetJobsUC["get-jobs Usecase"]:::business
        click GetJobsUC "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/usecases/jobs/get-jobs.usecase.ts"
        GetJobByIdUC["get-job-by-id Usecase"]:::business
        click GetJobByIdUC "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/usecases/jobs/get-job-by-id.usecase.ts"
        GetJobResultUC["get-job-result Usecase"]:::business
        click GetJobResultUC "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/usecases/jobs/get-job-result.usecase.ts"
        TranscribeUC["transcribe-workflow Usecase"]:::business
        click TranscribeUC "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/usecases/media/transcribe-workflow.usecase.ts"
    end

    %% Steps / Workflow Engine
    subgraph "Steps"
        direction TB
        Download["download-link Step"]:::business
        click Download "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/steps/media/download-link.step.ts"
        TranscribeStep["transcribe-media Step"]:::business
        click TranscribeStep "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/steps/media/transcribe-media.step.ts"
        Persist["persist-subtitles Step"]:::business
        click Persist "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/steps/media/persist-subtitles.step.ts"
    end

    %% Store Layer
    subgraph "Stores"
        direction TB
        JobsStore["Jobs Store"]:::store
        click JobsStore "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/stores/jobs/jobs.store.ts"
        MediaStore["Media Store"]:::store
        click MediaStore "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/stores/media/media.store.ts"
        WorkflowStore["Workflow Store"]:::store
        click WorkflowStore "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/stores/workflow/workflow-store.ts"
    end

    %% Domain Models
    subgraph "Domain Models"
        direction TB
        CommonSchema["Common Schema"]:::domain
        click CommonSchema "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/domain/common/schema.ts"
        JobsSchema["Jobs Schema"]:::domain
        click JobsSchema "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/domain/jobs/jobs.schema.ts"
        JobsErrors["Jobs Errors"]:::domain
        click JobsErrors "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/domain/jobs/jobs.errors.ts"
        MediaSchema["Media Schema"]:::domain
        click MediaSchema "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/domain/media/media.schema.ts"
        MediaErrors["Media Errors"]:::domain
        click MediaErrors "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/domain/media/media.errors.ts"
        WorkflowSchema["Workflow Schema"]:::domain
        click WorkflowSchema "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/domain/workflow/workflow.schema.ts"
        WorkflowErrors["Workflow Errors"]:::domain
        click WorkflowErrors "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/domain/workflow/workflow.errors.ts"
    end

    %% Platform Adapter
    Platform["Platform Adapter (s3-fs)"]:::external
    click Platform "https://github.com/bleedingdev/coursition-effect.experiment/blob/master/src/platform/s3-fs.ts"

    %% External Services
    DB["Database (JOBS_TABLE)"]:::external
    S3["S3 Bucket"]:::external

    %% Connections
    Client -->|"HTTP Request"| Server
    Server -->|"routes via API definitions"| API
    Server --> Config
    API -->|"dispatch"| GetJobs
    API -->|"dispatch"| GetJobById
    API -->|"dispatch"| GetJobResult
    API -->|"dispatch"| TranscribeHandler

    GetJobs -->|"call"| GetJobsUC
    GetJobById -->|"call"| GetJobByIdUC
    GetJobResult -->|"call"| GetJobResultUC
    TranscribeHandler -->|"call"| TranscribeUC

    GetJobsUC -->|"CRUD"| JobsStore
    GetJobByIdUC -->|"CRUD"| JobsStore
    GetJobResultUC -->|"CRUD"| JobsStore

    TranscribeUC -->|"invoke steps"| Download
    Download -->|"next"| TranscribeStep
    TranscribeStep -->|"next"| Persist
    Persist -->|"store info"| MediaStore

    JobsStore -->|"persist metadata"| DB
    MediaStore -->|"persist media info"| DB

    Download -->|"fetch/upload"| Platform
    Platform -->|"object storage"| S3

    %% Class Definitions
    classDef api fill:#ADD8E6,stroke:#000;
    classDef business fill:#90EE90,stroke:#000;
    classDef store fill:#FFA500,stroke:#000;
    classDef domain fill:#D3D3D3,stroke:#000;
    classDef external fill:#DDA0DD,stroke:#000;
    classDef config fill:#F0E68C,stroke:#000;
```
