# kma-score/kma_score_serverless architecture

> Architecture diagram of the GitHub repository kma-score/kma_score_serverless, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kma-score/kma_score_serverless
- Repository: https://github.com/kma-score/kma_score_serverless

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Request flow
    EC["External Client"]:::external
    AG["API Gateway"]:::aws
    LF["Lambda Functions"]:::functions
    MW["Auth Middleware"]:::middleware

    %% Core Package subgraph
    subgraph "Core Business Logic (Core Package)"
        D["Domain Layer"]:::domain
        A["Application Layer"]:::application
        INF["Infrastructure Layer"]:::infra
        SM["Shared Modules"]:::shared
        DI["Dependency Injection Container"]:::container
    end

    %% Database subgraph
    subgraph "Database"
        DC["Database Config"]:::database
        SQL["SQL Migrations"]:::database
    end

    %% Infrastructure as Code subgraph
    subgraph "AWS Deployment (IaC)"
        IAC["API Deployment Stacks"]:::iac
    end

    %% Connections for External Requests
    EC -->|"sends request"| AG
    AG -->|"triggers"| LF
    LF -->|"executes"| MW
    MW -->|"calls"| A

    %% Connections within Core Package
    A -->|"uses"| D
    A -->|"delegates to"| INF
    DI -->|"wires"| A

    %% Infrastructure Layer to Database
    INF -->|"persists data in"| DC
    INF -->|"runs migrations on"| SQL

    %% IaC deployment influences
    IAC -->|"deploys"| AG
    IAC -->|"deploys"| LF

    %% Styles
    classDef external fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef aws fill:#87CEFA,stroke:#1E90FF,stroke-width:2px;
    classDef functions fill:#FFA500,stroke:#FF8C00,stroke-width:2px;
    classDef middleware fill:#FFB6C1,stroke:#FF69B4,stroke-width:2px;
    classDef domain fill:#ADD8E6,stroke:#0000CD,stroke-width:2px;
    classDef application fill:#90EE90,stroke:#008000,stroke-width:2px;
    classDef infra fill:#D3D3D3,stroke:#696969,stroke-width:2px;
    classDef shared fill:#E6E6FA,stroke:#9370DB,stroke-width:2px;
    classDef container fill:#F5DEB3,stroke:#D2691E,stroke-width:2px;
    classDef database fill:#FFFF99,stroke:#CCCC00,stroke-width:2px;
    classDef iac fill:#D8BFD8,stroke:#8A2BE2,stroke-width:2px;

    %% Click Events for Component Mapping
    click D "https://github.com/kma-score/kma_score_serverless/tree/main/packages/core/src/domain"
    click A "https://github.com/kma-score/kma_score_serverless/tree/main/packages/core/src/application"
    click INF "https://github.com/kma-score/kma_score_serverless/tree/main/packages/core/src/infra"
    click SM "https://github.com/kma-score/kma_score_serverless/tree/main/packages/core/src/shared"
    click DI "https://github.com/kma-score/kma_score_serverless/tree/main/packages/core/src/container"
    click LF "https://github.com/kma-score/kma_score_serverless/tree/main/packages/functions/src"
    click MW "https://github.com/kma-score/kma_score_serverless/tree/main/packages/functions/src/shared/middleware"
    click DC "https://github.com/kma-score/kma_score_serverless/blob/main/packages/core/drizzle.config.ts"
    click SQL "https://github.com/kma-score/kma_score_serverless/tree/main/packages/core/migrations"
    click IAC "https://github.com/kma-score/kma_score_serverless/blob/main/stacks/ApiStack.ts"
```
