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