# 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-06-24). 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 backend media-parsing microservice (written in TypeScript with Effect-TS) that exposes a REST API for submitting media parsing jobs and retrieving results. It is not a full front-end application, but it does include an API client module so other services or UIs can interact with it in a type-safe way.

##### File structure and its implications
- Top-level files:
- api.ts and client.ts define the public API schema and a built-in client for consumers
- server.ts sets up the HTTP server
- config.ts centralizes environment config
- Layered directories under src/:
- domain/ holds the core business schemas, errors, and types for jobs and media
- stores/ implements data access operations (e.g., persisting jobs to a database table, retrieving media parsing data)
- usecases/ contains business logic orchestrating domain rules, calling stores or external services
- Tests exist alongside handlers, usecases, and stores to verify each layer in isolation.

##### Core components
a. API Client (consumer library)
b. HTTP Server / API Gateway
c. Handlers Layer
d. Use-case Layer (business logic)
e. Data Store Layer (database access)
f. External Parsing Engine (third-party service at PARSING_ENGINE_URL)
g. Configuration Service (provides PORT, JOBS_TABLE, LOG_LEVEL, etc.)
h. Observability (logging & tracing cross-cuts all layers)

##### Relationships and interactions
- Data flow:
1. API Consumer → API Client (if internal call) or Directly → HTTP Server
2. HTTP Server routes to appropriate Handler (POST /media/parse, GET /media/jobs, etc.)
3. Handler invokes a Use Case (e.g., parse-media, get-jobs, get-job-by-id)
4. Use Case may call:
- Store layer for reading/writing to JOBS_TABLE
- External Parsing Engine service to perform media parsing
- Domain validation on input and error mapping
5. Store layer interacts with the database (e.g., DynamoDB or relational DB)
6. Use Case returns result or domain error to Handler
7. Handler maps domain errors to HTTP responses and returns JSON
- Configuration and logging are injected into each layer (cross-cutting).

##### Architectural patterns and design principles
- Layered architecture (Handlers → Use Cases → Stores → Database)
- Domain-driven design (schemas, errors, domain models under domain/)
- Effect-TS functional patterns for error handling and side-effect management
- Separation of concerns: handlers handle transport, usecases handle business logic, stores handle persistence
- Dependency injection of config and observability at every layer

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client & API"
        APIClient["API Client (consumer library)"]:::transport
        APISchema["Public API Schema"]:::transport
    end
    click APIClient "https://github.com/bleedingdev/coursition-effect-experiment/blob/master/src/client.ts"
    click APISchema "https://github.com/bleedingdev/coursition-effect-experiment/blob/master/src/api.ts"

    Server["HTTP Server / API Gateway"]:::transport
    click Server "https://github.com/bleedingdev/coursition-effect-experiment/blob/master/src/server.ts"

    subgraph "Handlers Layer"
        GetJobsH["get-jobs.handler.ts"]:::transport
        GetJobByIdH["get-job-by-id.handler.ts"]:::transport
        GetJobResultH["get-job-result.handler.ts"]:::transport
        ParseMediaH["parse-media.handler.ts"]:::transport
    end
    click GetJobsH "https://github.com/bleedingdev/coursition-effect-experiment/blob/master/src/handlers/jobs/get-jobs.handler.ts"
    click GetJobByIdH "https://github.com/bleedingdev/coursition-effect-experiment/blob/master/src/handlers/jobs/get-job-by-id.handler.ts"
    click GetJobResultH "https://github.com/bleedingdev/coursition-effect-experiment/blob/master/src/handlers/jobs/get-job-result.handler.ts"
    click ParseMediaH "https://github.com/bleedingdev/coursition-effect-experiment/blob/master/src/handlers/media/parse-media.handler.ts"

    subgraph "Domain Models & Errors"
        CommonSchema["common/schema.ts"]:::logic
        JobsSchema["jobs.schema.ts"]:::logic
        JobsErrors["jobs.errors.ts"]:::logic
        MediaSchema["media.schema.ts"]:::logic
        MediaErrors["media.errors.ts"]:::logic
    end
    click CommonSchema "https://github.com/bleedingdev/coursition-effect-experiment/blob/master/src/domain/common/schema.ts"
    click JobsSchema "https://github.com/bleedingdev/coursition-effect-experiment/blob/master/src/domain/jobs/jobs.schema.ts"
    click JobsErrors "https://github.com/bleedingdev/coursition-effect-experiment/blob/master/src/domain/jobs/jobs.errors.ts"
    click MediaSchema "https://github.com/bleedingdev/coursition-effect-experiment/blob/master/src/domain/media/media.schema.ts"
    click MediaErrors "https://github.com/bleedingdev/coursition-effect-experiment/blob/master/src/domain/media/media.errors.ts"

    subgraph "Use Cases Layer"
        GetJobsUC["get-jobs.usecase.ts"]:::logic
        GetJobByIdUC["get-job-by-id.usecase.ts"]:::logic
        GetJobResultUC["get-job-result.usecase.ts"]:::logic
        ParseMediaUC["parse-media.usecase.ts"]:::logic
    end
    click GetJobsUC "https://github.com/bleedingdev/coursition-effect-experiment/blob/master/src/usecases/jobs/get-jobs.usecase.ts"
    click GetJobByIdUC "https://github.com/bleedingdev/coursition-effect-experiment/blob/master/src/usecases/jobs/get-job-by-id.usecase.ts"
    click GetJobResultUC "https://github.com/bleedingdev/coursition-effect-experiment/blob/master/src/usecases/jobs/get-job-result.usecase.ts"
    click ParseMediaUC "https://github.com/bleedingdev/coursition-effect-experiment/blob/master/src/usecases/media/parse-media.usecase.ts"

    subgraph "Data Store Layer"
        JobsStore["jobs.store.ts"]:::data
        MediaStore["media.store.ts"]:::data
    end
    click JobsStore "https://github.com/bleedingdev/coursition-effect-experiment/blob/master/src/stores/jobs/jobs.store.ts"
    click MediaStore "https://github.com/bleedingdev/coursition-effect-experiment/blob/master/src/stores/media/media.store.ts"

    DB[(Database)]:::data

    External["External Parsing Engine"]:::external

    Config["Configuration Service"]:::config
    click Config "https://github.com/bleedingdev/coursition-effect-experiment/blob/master/src/config.ts"
    Observability["Observability (Logging & Tracing)"]:::cross

    APIClient -->|"requests via client"| Server
    APISchema --> Server

    Server -->|routes request| GetJobsH
    Server -->|routes request| GetJobByIdH
    Server -->|routes request| GetJobResultH
    Server -->|routes request| ParseMediaH

    GetJobsH -->|"invoke"| GetJobsUC
    GetJobByIdH -->|"invoke"| GetJobByIdUC
    GetJobResultH -->|"invoke"| GetJobResultUC
    ParseMediaH -->|"invoke"| ParseMediaUC

    CommonSchema --> GetJobsUC
    JobsSchema --> GetJobsUC
    JobsErrors -.-> GetJobByIdUC
    MediaSchema --> ParseMediaUC
    MediaErrors -.-> ParseMediaUC

    GetJobsUC -->|read/write| JobsStore
    GetJobByIdUC -->|read/write| JobsStore
    GetJobResultUC -->|read/write| JobsStore
    ParseMediaUC -->|save job| JobsStore
    ParseMediaUC -->|call parsing| External
    ParseMediaUC -->|update status| MediaStore

    JobsStore --> DB
    MediaStore --> DB

    Config -.-> APIClient
    Config -.-> Server
    Config -.-> GetJobsH
    Config -.-> GetJobByIdH
    Config -.-> GetJobResultH
    Config -.-> ParseMediaH
    Config -.-> GetJobsUC
    Config -.-> GetJobByIdUC
    Config -.-> GetJobResultUC
    Config -.-> ParseMediaUC
    Config -.-> JobsStore
    Config -.-> MediaStore

    Observability -.-> Server
    Observability -.-> GetJobsH
    Observability -.-> GetJobByIdH
    Observability -.-> GetJobResultH
    Observability -.-> ParseMediaH
    Observability -.-> GetJobsUC
    Observability -.-> GetJobByIdUC
    Observability -.-> GetJobResultUC
    Observability -.-> ParseMediaUC
    Observability -.-> JobsStore
    Observability -.-> MediaStore

    classDef transport fill:#cce5ff,stroke:#004085,color:#004085
    classDef logic fill:#d4edda,stroke:#155724,color:#155724
    classDef data fill:#fff3cd,stroke:#856404,color:#856404
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef config fill:#f3e5f5,stroke:#6a1b9a,color:#6a1b9a
    classDef cross fill:#e2e3e5,stroke-dasharray:2 2,color:#343a40
```
