# opetushallitus/koto-rekisteri architecture

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

- Interactive diagram: https://gitdiagram.com/opetushallitus/koto-rekisteri
- Repository: https://github.com/opetushallitus/koto-rekisteri

## Overview

##### Project Type and Purpose
- The project is a full-stack system that mainly centers on a backend service (written in Kotlin and built with Maven, likely using Spring Boot) dealing with language test/assessment functionalities (e.g., “yki” and “kotoutumiskoulutus”) as seen from the controllers, services, and domain models.
- It is supported by extensive infrastructure components deployed via AWS CDK (inside the “infra” directory) and includes automated e2e tests (using Playwright in the “e2e” folder).
- The README and file structure indicate a project that handles API requests, communicates with external services (like AWS Secrets Manager and Slack), and integrates with a backend database (via migration scripts in the resources folder).

##### File Structure – Key Components
- Server Directory:
- Core business logic resides under server/src/main/kotlin, with various packages for authentication, CSV parsing, database integration, logging, observability, and domain-specific operations (e.g., yki, kotoutumiskoulutus).
- Configuration files (application.properties and environment-specific properties) and database migration scripts (inside server/src/main/resources/db/migration) indicate a relational database backend.
- The controllers (HomeController, YkiApiController, etc.) and other web components (like Mustache templates) show that the server is a web application/API backend.
- Infra Directory:
- Contains AWS CDK stacks (e.g., db-stack, network-stack, service-stack, slack-bot-stack) along with utility stacks and configuration scripts. This represents the deployment and operational infrastructure for the application.
- The infra folder further defines separate environments (Dev, Test, Prod) and includes testing resources.
- e2e Directory:
- Holds end-to-end (E2E) tests written in TypeScript (Playwright). These tests simulate user interactions and validate the integrated system.
- Scripts, Docker, and Other Files:
- Various scripts (e.g., start_local_env.sh, start_local_server.sh) are used for setting up the development environment, database initialization, and container orchestration (Docker-compose, Dockerfile).
- Configuration files (e.g., .dockerignore, .prettierrc, mise configuration files) support tooling and code quality enforcement.

##### Extracting Key Architectural and Deployment Insights
- The system is designed for multi-environment deployments (dev, test, prod) on AWS, using CI/CD pipelines provided by GitHub Actions.
- The server communicates with external AWS components (Secrets Manager, AWS Chatbot for Slack alerts) and likely interacts with a relational database.
- Deployment scripts in the infra folder illustrate that infrastructure is automated via CDK and incorporate several AWS services (e.g., networking, container repositories, alarms, backups, GitHub Actions integration).

##### Components
a. Primary Components:
- Frontend / Client Layer (if any): Even if not explicitly present, note that E2E tests simulate an external client or web browser interaction.
- Backend Server: Represent the Kotlin-based API server (Spring Boot) with its controllers, services, and data access layers.
- Database: Depicted as the persistent storage, referenced via migration scripts and repositories.
- Infrastructure Components: AWS CDK stacks that handle the network setup, container repositories, alarms, backups, log groups, and Slack notifier.
- External Services: AWS Secrets Manager (for configuration and credentials), Slack (for alert notifications), and possibly external APIs (e.g., Oppijanumero service).
- Development and Testing Tools: Representation of the tooling, including Docker, mise (for dependency management), and Playwright for E2E tests.

b. Relationships and Data Flows:
- Directional flows from external clients (or test clients) sending requests to the backend API.
- The backend communicates with the Database for persistent data operations.
- The backend uses AWS Secrets Manager for credentials and configuration, and sends alerts (via Slack) through the configured notifier.
- Deployment pipelines (GitHub Actions) trigger automatic deployments through the infra stacks (CDK), which in turn configure AWS services.
- E2E tests interact with the live backend and simulate user behavior to validate system operations.

c. Architectural Patterns and Design Principles:
- Multi-layered architecture: Separates API business logic, data access, and infrastructure concerns.
- Infrastructure as Code: Employed via AWS CDK stacks to maintain consistency across different AWS environments.
- Modular design: The backend code is organized into cohesive packages (e.g., authentication, logging, domain-specific modules) that follow best practices in microservice or layered architecture.
- Testability: Evidenced by comprehensive e2e tests and unit tests in the server module.

##### Final Assembly
- Clarity by breaking the system down into as many components as possible while preserving the logical relationships among them.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Testing & Client Layer
    subgraph "Testing & Client Layer"
        E2E["E2E Tests / Web Client"]:::testing
    end

    %% Backend Layer
    subgraph "Backend Layer"
        API["Kotlin API Server"]:::backend
        YKI["Domain: Yki Module"]:::backend
        KOT["Domain: Kotoutumiskoulutus Module"]:::backend
    end

    %% Database Layer
    DB["PostgreSQL Database"]:::database

    %% External Services
    SM["AWS Secrets Manager"]:::external
    SLACK["Slack Notifier"]:::external

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        CDK["AWS CDK Stacks"]:::infrastructure
    end

    %% Automation & Scripts
    CICD["GitHub Actions Pipeline"]:::infrastructure
    DEV["Dev & Deployment Scripts"]:::testing

    %% Connections
    E2E -->|"calls"| API
    API -->|"processes"| YKI
    API -->|"processes"| KOT
    API -->|"queries"| DB
    API -->|"fetches"| SM
    API -->|"alerts"| SLACK
    CICD -->|"deploys"| CDK
    DEV -->|"sets_up"| API

    %% Styles
    classDef backend fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef infrastructure fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef testing fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef database fill:#FFE4B5,stroke:#333,stroke-width:2px;
    classDef external fill:#DDA0DD,stroke:#333,stroke-width:2px;

    %% Click Events
    click API "https://github.com/opetushallitus/koto-rekisteri/tree/main/server/src/main/kotlin/fi/oph/kitu"
    click YKI "https://github.com/opetushallitus/koto-rekisteri/tree/main/server/src/main/kotlin/fi/oph/kitu/yki"
    click KOT "https://github.com/opetushallitus/koto-rekisteri/tree/main/server/src/main/kotlin/fi/oph/kitu/kotoutumiskoulutus"
    click DB "https://github.com/opetushallitus/koto-rekisteri/tree/main/server/src/main/resources/db/migration"
    click CDK "https://github.com/opetushallitus/koto-rekisteri/tree/main/infra"
    click E2E "https://github.com/opetushallitus/koto-rekisteri/tree/main/e2e"
    click DEV "https://github.com/opetushallitus/koto-rekisteri/tree/main/scripts"
    click CICD "https://github.com/opetushallitus/koto-rekisteri/tree/main/.github/workflows"
```
