# opetushallitus/kieli-ja-kaantajatutkinnot architecture

> Architecture diagram of the GitHub repository opetushallitus/kieli-ja-kaantajatutkinnot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/opetushallitus/kieli-ja-kaantajatutkinnot
- Repository: https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot

## Overview

This monorepo hosts four Finnish National Agency for Education services: AKR translator authorization, OTR interpreter qualification, VKT language-exam enrollment and results, and YKI exam-session registration. The principal VKT journey is public enrollment into an exam event, followed by examiner appointment/grade handling and register synchronization; clerks manage events and enrollments. AKR and OTR expose public registries and clerk administration, while YKI manages exam sessions and registrations. The graph emphasizes documented capabilities and sampled call paths; YKI and several unsampled integrations are represented only at subsystem level.

Main entry points: [`backend/akr/src/main/java/fi/oph/akr/service/ClerkTranslatorService.java`](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/akr/src/main/java/fi/oph/akr/service/ClerkTranslatorService.java) (Authorization management), [`backend/otr/src/main/java/fi/oph/otr/service/ClerkInterpreterService.java`](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/otr/src/main/java/fi/oph/otr/service/ClerkInterpreterService.java) (Qualification management), [`backend/vkt/src/main/java/fi/oph/vkt/service/PublicEnrollmentService.java`](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/vkt/src/main/java/fi/oph/vkt/service/PublicEnrollmentService.java) (Enrollment and queue), [`backend/vkt/src/main/java/fi/oph/vkt/service/ExaminerEnrollmentService.java`](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/vkt/src/main/java/fi/oph/vkt/service/ExaminerEnrollmentService.java) (Appointments and grades)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_akr["AKR translators"]
  node_akr_public_api["Translator API"]
  node_akr_public_service["Public registry search"]
  node_akr_clerk_api["Translator administration"]
  node_akr_clerk_service["Authorization management"]
  node_akr_data[("Translator records")]
end

subgraph group_otr["OTR interpreters"]
  node_otr_public_api["Interpreter API"]
  node_otr_public_service["Public interpreter search"]
  node_otr_clerk_api["Interpreter administration"]
  node_otr_clerk_service["Qualification management"]
  node_otr_data[("Interpreter records")]
end

subgraph group_vkt["VKT exams"]
  node_vkt_public_api["Public enrollment API"]
  node_vkt_public_service["Enrollment and queue"]
  node_vkt_clerk_api["Clerk enrollment API"]
  node_vkt_clerk_service["Clerk enrollment operations"]
  node_vkt_examiner_api["Examiner enrollment API"]
  node_vkt_examiner_service["Appointments and grades"]
  node_vkt_data[("Exam enrollment data")]
  node_vkt_email["Enrollment notifications"]
  node_vkt_register["Register synchronization"]
end

subgraph group_yki["YKI sessions"]
  node_yki_sessions["Exam sessions and registrations"]
  node_yki_auth["Public session identity"]
end

subgraph group_shared["Shared integrations"]
  node_onr["ONR personal data<br/>[OnrService.java]"]
  node_mail["Email delivery"]
end

node_public(("Public users"))
node_clerk(("Clerk users"))
node_examiner(("Examiner users"))
node_registry[("Language register")]

node_public -->|"requests"| node_akr_public_api
node_akr_public_api -->|"delegates"| node_akr_public_service
node_clerk -->|"requests"| node_akr_clerk_api
node_akr_clerk_api -->|"delegates"| node_akr_clerk_service
node_akr_clerk_service -->|"reads or updates"| node_onr
node_akr_clerk_service -->|"persists records"| node_akr_data
node_public -->|"requests"| node_otr_public_api
node_otr_public_api -->|"delegates"| node_otr_public_service
node_clerk -->|"requests"| node_otr_clerk_api
node_otr_clerk_api -->|"delegates"| node_otr_clerk_service
node_otr_clerk_service -->|"reads or updates"| node_onr
node_otr_clerk_service -->|"persists records"| node_otr_data
node_public -->|"enrolls"| node_vkt_public_api
node_vkt_public_api -->|"delegates"| node_vkt_public_service
node_vkt_public_service -->|"validates and saves"| node_vkt_data
node_vkt_public_service -->|"sends confirmations"| node_vkt_email
node_vkt_email -->|"delivers email"| node_mail
node_clerk -->|"manages enrollment"| node_vkt_clerk_api
node_vkt_clerk_api -->|"delegates"| node_vkt_clerk_service
node_examiner -->|"handles enrollment"| node_vkt_examiner_api
node_vkt_examiner_api -->|"delegates"| node_vkt_examiner_service
node_vkt_examiner_service -->|"updates grades"| node_vkt_data
node_vkt_examiner_service -.->|"graded results"| node_vkt_register
node_vkt_register -.->|"syncs results"| node_registry
node_clerk -->|"manages sessions"| node_yki_sessions

click node_akr_public_api "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/akr/src/main/java/fi/oph/akr/api/translator/TranslatorController.java"
click node_akr_public_service "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/akr/src/main/java/fi/oph/akr/service/PublicTranslatorService.java"
click node_akr_clerk_api "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/akr/src/main/java/fi/oph/akr/api/clerk/ClerkTranslatorController.java"
click node_akr_clerk_service "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/akr/src/main/java/fi/oph/akr/service/ClerkTranslatorService.java"
click node_akr_data "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/akr/src/main/java/fi/oph/akr/repository/TranslatorRepository.java"
click node_otr_public_api "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/otr/src/main/java/fi/oph/otr/api/PublicController.java"
click node_otr_public_service "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/otr/src/main/java/fi/oph/otr/service/PublicInterpreterService.java"
click node_otr_clerk_api "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/otr/src/main/java/fi/oph/otr/api/clerk/ClerkInterpreterController.java"
click node_otr_clerk_service "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/otr/src/main/java/fi/oph/otr/service/ClerkInterpreterService.java"
click node_otr_data "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/otr/src/main/java/fi/oph/otr/repository/InterpreterRepository.java"
click node_vkt_public_api "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/vkt/src/main/java/fi/oph/vkt/api/PublicController.java"
click node_vkt_public_service "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/vkt/src/main/java/fi/oph/vkt/service/PublicEnrollmentService.java"
click node_vkt_clerk_api "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/vkt/src/main/java/fi/oph/vkt/api/clerk/ClerkEnrollmentController.java"
click node_vkt_clerk_service "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/vkt/src/main/java/fi/oph/vkt/service/ClerkEnrollmentService.java"
click node_vkt_examiner_api "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/vkt/src/main/java/fi/oph/vkt/api/examiner/ExaminerEnrollmentController.java"
click node_vkt_examiner_service "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/vkt/src/main/java/fi/oph/vkt/service/ExaminerEnrollmentService.java"
click node_vkt_data "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/tree/dev/backend/vkt/src/main/java/fi/oph/vkt/service"
click node_vkt_email "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/vkt/src/main/java/fi/oph/vkt/service/PublicEnrollmentEmailService.java"
click node_vkt_register "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/vkt/src/main/java/fi/oph/vkt/service/RegisterEnrollmentService.java"
click node_yki_sessions "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/yki/src/main/java/fi/oph/yki/service/ClerkExamSessionService.java"
click node_yki_auth "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/yki/src/main/java/fi/oph/yki/service/PublicAuthService.java"
click node_onr "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/akr/src/main/java/fi/oph/akr/onr/OnrService.java"
click node_mail "https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/vkt/src/main/java/fi/oph/vkt/service/PublicEnrollmentEmailService.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_akr_public_api,node_akr_public_service,node_akr_clerk_api,node_akr_clerk_service,node_akr_data,node_public,node_clerk,node_examiner toneBlue
class node_otr_public_api,node_otr_public_service,node_otr_clerk_api,node_otr_clerk_service,node_otr_data,node_registry toneAmber
class node_vkt_public_api,node_vkt_public_service,node_vkt_clerk_api,node_vkt_clerk_service,node_vkt_examiner_api,node_vkt_examiner_service,node_vkt_data,node_vkt_email,node_vkt_register toneMint
class node_yki_sessions,node_yki_auth toneRose
class node_onr,node_mail toneIndigo
```

## Components

### AKR translators

- [Translator API](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/akr/src/main/java/fi/oph/akr/api/translator/TranslatorController.java): `backend/akr/src/main/java/fi/oph/akr/api/translator/TranslatorController.java`
- [Public registry search](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/akr/src/main/java/fi/oph/akr/service/PublicTranslatorService.java): `backend/akr/src/main/java/fi/oph/akr/service/PublicTranslatorService.java`
- [Translator administration](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/akr/src/main/java/fi/oph/akr/api/clerk/ClerkTranslatorController.java): `backend/akr/src/main/java/fi/oph/akr/api/clerk/ClerkTranslatorController.java`
- [Authorization management](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/akr/src/main/java/fi/oph/akr/service/ClerkTranslatorService.java): `backend/akr/src/main/java/fi/oph/akr/service/ClerkTranslatorService.java`
- [Translator records](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/akr/src/main/java/fi/oph/akr/repository/TranslatorRepository.java): `backend/akr/src/main/java/fi/oph/akr/repository/TranslatorRepository.java`

### OTR interpreters

- [Interpreter API](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/otr/src/main/java/fi/oph/otr/api/PublicController.java): `backend/otr/src/main/java/fi/oph/otr/api/PublicController.java`
- [Public interpreter search](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/otr/src/main/java/fi/oph/otr/service/PublicInterpreterService.java): `backend/otr/src/main/java/fi/oph/otr/service/PublicInterpreterService.java`
- [Interpreter administration](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/otr/src/main/java/fi/oph/otr/api/clerk/ClerkInterpreterController.java): `backend/otr/src/main/java/fi/oph/otr/api/clerk/ClerkInterpreterController.java`
- [Qualification management](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/otr/src/main/java/fi/oph/otr/service/ClerkInterpreterService.java): `backend/otr/src/main/java/fi/oph/otr/service/ClerkInterpreterService.java`
- [Interpreter records](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/otr/src/main/java/fi/oph/otr/repository/InterpreterRepository.java): `backend/otr/src/main/java/fi/oph/otr/repository/InterpreterRepository.java`

### VKT exams

- [Public enrollment API](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/vkt/src/main/java/fi/oph/vkt/api/PublicController.java): `backend/vkt/src/main/java/fi/oph/vkt/api/PublicController.java`
- [Enrollment and queue](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/vkt/src/main/java/fi/oph/vkt/service/PublicEnrollmentService.java): `backend/vkt/src/main/java/fi/oph/vkt/service/PublicEnrollmentService.java`
- [Clerk enrollment API](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/vkt/src/main/java/fi/oph/vkt/api/clerk/ClerkEnrollmentController.java): `backend/vkt/src/main/java/fi/oph/vkt/api/clerk/ClerkEnrollmentController.java`
- [Clerk enrollment operations](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/vkt/src/main/java/fi/oph/vkt/service/ClerkEnrollmentService.java): `backend/vkt/src/main/java/fi/oph/vkt/service/ClerkEnrollmentService.java`
- [Examiner enrollment API](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/vkt/src/main/java/fi/oph/vkt/api/examiner/ExaminerEnrollmentController.java): `backend/vkt/src/main/java/fi/oph/vkt/api/examiner/ExaminerEnrollmentController.java`
- [Appointments and grades](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/vkt/src/main/java/fi/oph/vkt/service/ExaminerEnrollmentService.java): `backend/vkt/src/main/java/fi/oph/vkt/service/ExaminerEnrollmentService.java`
- [Exam enrollment data](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/tree/dev/backend/vkt/src/main/java/fi/oph/vkt/service): `backend/vkt/src/main/java/fi/oph/vkt/service`
- [Enrollment notifications](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/vkt/src/main/java/fi/oph/vkt/service/PublicEnrollmentEmailService.java): `backend/vkt/src/main/java/fi/oph/vkt/service/PublicEnrollmentEmailService.java`
- [Register synchronization](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/vkt/src/main/java/fi/oph/vkt/service/RegisterEnrollmentService.java): `backend/vkt/src/main/java/fi/oph/vkt/service/RegisterEnrollmentService.java`

### YKI sessions

- [Exam sessions and registrations](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/yki/src/main/java/fi/oph/yki/service/ClerkExamSessionService.java): `backend/yki/src/main/java/fi/oph/yki/service/ClerkExamSessionService.java`
- [Public session identity](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/yki/src/main/java/fi/oph/yki/service/PublicAuthService.java): `backend/yki/src/main/java/fi/oph/yki/service/PublicAuthService.java`

### Shared integrations

- [ONR personal data](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/akr/src/main/java/fi/oph/akr/onr/OnrService.java): `backend/akr/src/main/java/fi/oph/akr/onr/OnrService.java`
- [Email delivery](https://github.com/opetushallitus/kieli-ja-kaantajatutkinnot/blob/dev/backend/vkt/src/main/java/fi/oph/vkt/service/PublicEnrollmentEmailService.java): `backend/vkt/src/main/java/fi/oph/vkt/service/PublicEnrollmentEmailService.java`

### Other components

- **Public users**
- **Clerk users**
- **Examiner users**
- **Language register**

## Connections

- Public users → Translator API: requests
- Translator API → Public registry search: delegates
- Clerk users → Translator administration: requests
- Translator administration → Authorization management: delegates
- Authorization management → ONR personal data: reads or updates
- Authorization management → Translator records: persists records
- Public users → Interpreter API: requests
- Interpreter API → Public interpreter search: delegates
- Clerk users → Interpreter administration: requests
- Interpreter administration → Qualification management: delegates
- Qualification management → ONR personal data: reads or updates
- Qualification management → Interpreter records: persists records
- Public users → Public enrollment API: enrolls
- Public enrollment API → Enrollment and queue: delegates
- Enrollment and queue → Exam enrollment data: validates and saves
- Enrollment and queue → Enrollment notifications: sends confirmations
- Enrollment notifications → Email delivery: delivers email
- Clerk users → Clerk enrollment API: manages enrollment
- Clerk enrollment API → Clerk enrollment operations: delegates
- Examiner users → Examiner enrollment API: handles enrollment
- Examiner enrollment API → Appointments and grades: delegates
- Appointments and grades → Exam enrollment data: updates grades
- Appointments and grades → Register synchronization: graded results
- Register synchronization → Language register: syncs results
- Clerk users → Exam sessions and registrations: manages sessions