How bleedingdev/coursition-effect.experiment works
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.