How kma-score/kma_score_serverless works
Overview & Project Purpose
• This project is a serverless API for “KMA Score” built with TypeScript and deployed on AWS Lambda.
• The core business logic follows Domain Driven Design (DDD) and Clean Architecture, organized into a monorepo with distinct packages (core and functions) and stacks for infrastructure management.
• The objective of the API is to provide functionality associated with “KMA Score”, likely dealing with scheduling, student details, assessments, etc.
Key Components
• Core Package (Business Logic):
• Domain Layer: Represents core business entities and domain rules (e.g., student entities, subject entities, schedule).
• Application Layer: Contains useCases and ports defining interaction contracts with the outside world. It’s where business processes are implemented, separated by use case responsibilities (such as handling students, schedules, etc.).
• Infrastructure Layer: Implements external dependencies (database access, authentication services, Keycloak integration, schedule services, etc.) that satisfy the contracts defined in the application ports.
• Shared Modules: Offer error handling, utilities, query handling and common types used across layers.
• Dependency Injection Container: Managed through the container folder which uses Awilix to wire up use cases and infra implementations.
• Functions Package (AWS Lambda Functions):
• Serverless entry points that expose the business logic through Lambda functions.
• Organized into folders for different endpoints such as schedule, student, and user functions.
• Contains middleware for authentication and request validation, directing incoming API requests to the correct business logic.
• Infrastructure as Code (stacks):
• The stacks folder contains IaC scripts (e.g., ApiStack.ts) used to deploy and configure the AWS environment (API Gateway, Lambda functions, possibly Lambda layers, etc.).
• Database & Migrations:
• Within packages/core, there are database configurations (drizzle.config.ts) and SQL migration files. This indicates database interactions which should be depicted as a separate component (e.g., a database service).
Relationships and Data Flow
• Incoming external API requests (from AWS API Gateway) hit the Lambda functions in the functions package.
• Lambda functions leverage middleware (authentication/validation) before routing calls to the core business logic.
• The Core package’s Application Layer (use cases) orchestrates the business workflows:
• It interacts with Domain Layer components to perform business computations.
• It communicates with Infrastructure Layer implementations to fulfill data persistence, external authentication (Keycloak), configuration, and scheduling tasks.
• The Dependency Injection Container (Awilix) in the core package manages the wiring of these components, ensuring the right dependencies (from infra services, database repositories, etc.) are injected where needed.
• The stacks (IaC) interact with all functions and possibly create necessary AWS resources (e.g., API Gateway, Lambda functions, layers) to run the service.
Architectural Patterns and Technologies
• Domain Driven Design (DDD) and Clean Architecture: Clear separation of concerns between domain, application, and infrastructure layers.
• Dependency Injection using Awilix: Manages dependency resolution within the core package.
• AWS Serverless stack: Lambda functions, API Gateway, and infrastructure defined in IaC (stacks folder).
• TypeScript as the primary language.
• Database migrations configured via Drizzle and SQL migration files.
• Middleware for cross-cutting concerns like authentication and request validation.