How opetushallitus/koto-rekisteri works
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.