Architecture-as-Code/ikt-arh-kultura-valodu-tehnologijas/README.md

IKT arhitektūra — Kultūras un valodu tehnoloģiju joma (SSOT)

Šis repozitorijs uztur jomas mērķarhitektūru kā kodu ("Architecture as Code"), kur visa informācija tiek glabāta strukturēti, versēti un atkārtojami ģenerējama.

Repozitorijs ir veidots kā SSOT (Single Source of Truth) — autoritatīvais saturs ir mašīnlasāmos YAML reģistros, bet cilvēklasāmais dokuments tiek ģenerēts no tiem. AI aģenti un automatizācijas rīki piekļūst šiem datiem caur MCP serveri.

---

1) Pamatideja (Architecture as Code)

Šajā repozitorijā arhitektūra tiek uzturēta šādi:

• Skati (views/) — cilvēklasāms dokuments (Markdown), kas nosaka dokumenta struktūru un stāstījumu
• Reģistri (registers/) — mašīnlasāmi dati (YAML), kas ir autoritatīvais avots visām entītijām
• Diagrammas (diagrams/) — Mermaid (šobrīd TODO vietturi)
• Attiecības (registers/99-relations/edges.yaml) — grafiks starp entītijām (95 šķautnes)

Repozitorijā visas entītijas tiek uzturētas kā vienumi (items), kuriem ir stabili identifikatori (ID) un atribūti. Piemēram, sys.valoda.02 ir "Lielais latviešu valodas modelis (LVM-LV)", goal.m4 ir "Latviešu valoda digitālajā laikmetā".

---

2) Repozitorija struktūra

.
├── domains/
│   └── kultura-valoda/
│       ├── manifest.yaml            # Domēna manifests
│       ├── views/                   # Dokumenta skati (Markdown)
│       │   ├── 01-ievads.md
│       │   ├── 02-esosas-arhitekturas-novertejums.md
│       │   ├── 03-merki-un-principi.md
│       │   ├── 04-merk-arhitektura.md
│       │   ├── 05-cela-karte.md
│       │   └── 06-pielikums-komponentu-katalogs.md
│       ├── registers/               # SSOT reģistri (YAML)
│       │   ├── 00-meta/             # Termini, saīsinājumi, saistītie dokumenti
│       │   ├── 02-goals/            # Stratēģiskie mērķi (M1–M6)
│       │   ├── 03-organizations/    # Institūcijas, lomas, atbildības
│       │   ├── 04-functions/        # Jomas funkcijas
│       │   ├── 05-services/         # Pakalpojumi (kultūra + valoda)
│       │   ├── 06-information-resources/  # Informācijas resursi
│       │   ├── 07-systems/          # Informācijas sistēmas
│       │   ├── 08-roadmap/          # Ceļa karte un mijiedarbības
│       │   ├── 09-risks/            # Riski un mazināšanas pasākumi
│       │   └── 99-relations/        # Attiecību grafiks (edges.yaml)
│       └── diagrams/                # Mermaid diagrammas (TODO)
├── mcp/                             # MCP serveris (AI aģentu interfeiss)
├── tools/
│   └── qa/                          # Kvalitātes pārbaudes skripti
└── docs/
    ├── MCP.md                       # MCP servera dokumentācija
    ├── TRACEABILITY.md
    └── REGENERATION.md

---

3) Skati (views/) — cilvēklasāms dokuments

Atrašanās vieta: domains/kultura-valoda/views/

Skati satur dokumenta nodaļu struktūru, virsrakstus un paskaidrojošu tekstu. Skatos ir atsauces uz reģistriem (backtick formātā), piemēram:

`registers/03-organizations/organizations.yaml`

Svarīgi: skatos nav jāuztur manuālas tabulas ar daudz vienumiem. Skati norāda "ko rādīt", bet saturs tiek ņemts no reģistriem. Dokumenta ģenerēšanas laikā atsauces tiek aizstātas ar reģistru saturu.

Pieejamie skati:

Skats	Apraksts
01-ievads.md	Ievads, tvērums, termini
02-esosas-arhitekturas-novertejums.md	Esošās arhitektūras novērtējums
03-merki-un-principi.md	Mērķi (M1–M6) un arhitektūras principi
04-merk-arhitektura.md	Mērķarhitektūra (funkcijas, pakalpojumi, sistēmas, IR)
05-cela-karte.md	Ceļa karte, riski, mijiedarbības
06-pielikums-komponentu-katalogs.md	Komponentu katalogs (pilns saraksts)

4) Reģistri (registers/) — mašīnlasāmi dati

Atrašanās vieta: domains/kultura-valoda/registers/

Reģistri ir YAML faili, kas satur vienumus. Šie reģistri ir SSOT un ir autoritatīvais avots.

Reģistrs	Saturs
00-meta/abbreviations.yaml	Saīsinājumi
00-meta/terms.yaml	Termini un definīcijas
00-meta/related-documents.yaml	Saistītie dokumenti
00-meta/legal-acts.yaml	Juridiskais regulējums (grupēts pa tēmām)
02-goals/goal-m1.yaml … goal-m6.yaml	Stratēģiskie mērķi
03-organizations/organizations.yaml	Institūcijas, lomas, atbildības
04-functions/functions.yaml	Jomas funkcijas (6 gab.)
05-services/kultura-services.yaml	Kultūras apakšjomas pakalpojumi (16 gab.)
05-services/valoda-services.yaml	Valodu tehnoloģiju pakalpojumi (14 gab.)
06-information-resources/kultura-info-resources.yaml	Kultūras informācijas resursi (15 gab.)
06-information-resources/valoda-info-resources.yaml	Valodu tehnoloģiju IR (8 gab.)
07-systems/kultura-systems.yaml	Kultūras IS (21 gab.)
07-systems/valoda-systems.yaml	Valodu tehnoloģiju IS (11 gab.)
08-roadmap/roadmap.yaml	Ceļa kartes pasākumi
08-roadmap/interactions.yaml	Mijiedarbība ar citām jomām
09-risks/risks.yaml	Riski un mazināšanas pasākumi
99-relations/edges.yaml	Attiecību grafiks (95 šķautnes)

5) Attiecības (edges.yaml) — grafiks starp vienumiem

Atrašanās vieta: domains/kultura-valoda/registers/99-relations/edges.yaml

Šis fails satur attiecības starp vienumiem. Katrai attiecībai ir from, type un to lauki.

Pieejamie attiecību tipi:

Tips	Nozīme
has_goal	Domēnam ir mērķis
has_function	Domēnam ir funkcija
has_service	Domēnam ir pakalpojums
has_system	Domēnam ir sistēma
has_information_resource	Domēnam ir informācijas resurss
owns / manages / operates	Organizācija ir īpašnieks / pārvaldītājs / operators
depends_on	Atkarība starp komponentēm
implements / supports / enables	Realizācijas un atbalsta saites
regulates / complies_with	Regulējuma saites

Pašlaik visas 95 šķautnes ir tipa domain.kultura-valoda → {entītija}, veidojot zvaigznes topoloģiju. Nākotnē grafiks tiks papildināts ar organizāciju, sistēmu un pakalpojumu savstarpējām saitēm.

6) Diagrammas (diagrams/) — Mermaid TODO vietturi

Atrašanās vieta: domains/kultura-valoda/diagrams/

Diagrammas tiek uzturētas Mermaid formātā. Šobrīd tās ir vietturi (TODO), kas nākotnē tiks aizstātas ar ģenerētām vai manuāli veidotām vizualizācijām.

---

7) Kā ģenerēt cilvēklasāmo dokumentu no SSOT

Repozitorijs nodrošina pilna mērķarhitektūras dokumenta automātisku ģenerēšanu no reģistriem un skatiem.

7.1 Priekšnosacījumi

• Node.js 18+ (ieteicams Node 20)
• npm

7.2 Uzstādīšana

No repozitorija saknes:

cd mcp
npm install

7.3 Dokumenta ģenerēšana (komandrinda)

No repozitorija saknes:

cd mcp
REPO_ROOT="$(pwd)/.." DOMAIN_DIR="domains/kultura-valoda" OUT_FILE="KISC-merkarhitektura-apraksts.md" npm run gen:doc

Rezultāts: KISC-merkarhitektura-apraksts.md (repo saknē).

7.4 Dokumenta ģenerēšana caur MCP serveri (AI aģents)

Ja MCP serveris darbojas, jebkurš AI aģents var ģenerēt dokumentu, izsaucot rīku generate_document:

Rīks: generate_document
Parametri:
  format: "markdown"        — Markdown formāts cilvēklasāmam dokumentam
  format: "json"            — JSON formāts mašīnapstrādei
  sections: ["ievads", "arhitektura", "celakarte"]  — konkrētas sadaļas (neobligāts)

Pilna dokumenta ģenerēšana (visas sadaļas):

generate_document(format="markdown")

Atsevišķu sadaļu ģenerēšana:

generate_document(format="markdown", sections=["ievads", "merki"])

Pieejamās sadaļas: ievads, esosa, merki, arhitektura, celakarte, katalogs.

Ģenerēšanas laikā tiek apvienoti visi skati (views/) ar tajā atsaucēto reģistru (registers/) saturu, veidojot vienotu, pilnu dokumentu.

7.5 Svarīgi par ģenerēto dokumentu

• Ģenerētais dokuments ir build artifact — tas netiek rediģēts manuāli.
• Izmaiņas vienmēr veic reģistros vai skatos, pēc tam atkārtoti ģenerē.
• Katru reizi ģenerējot, dokuments atspoguļo aktuālo SSOT stāvokli.

---

8) Kvalitātes kontrole (QA)

Repo ietver QA pārbaudes, lai nepieļautu satura zudumu.

No repozitorija saknes:

tools/qa/check_nonempty_registers.sh
tools/qa/check_generated_doc_headings.sh KISC-merkarhitektura-apraksts.md
tools/qa/check_stakeholder_count.sh KISC-merkarhitektura-apraksts.md

Ja QA neiziet — jālabo reģistri vai skati. Nedrīkst "saīsināt" saturu, lai tikai testi izietu.

---

9) MCP serveris — AI aģentu interfeiss

MCP (Model Context Protocol) serveris nodrošina AI aģentiem strukturētu piekļuvi arhitektūras SSOT datiem. Serveris darbojas kā tikai-lasīšanas slānis — tas nemaina SSOT saturu.

Detalizēta MCP servera dokumentācija, rīku apraksti, lietošanas scenāriji un piemēri ir pieejami atsevišķā dokumentā:

📖 docs/MCP.md — pilna MCP servera dokumentācija

9.1 Īsumā par iespējām

MCP serveris piedāvā 9 rīkus, kas ļauj AI aģentiem:

• Meklēt un izgūt jebkuru arhitektūras entītiju (mērķi, sistēmas, pakalpojumus, IR, riskus u.c.)
• Analizēt attiecības starp entītijām (grafu vaicājumi)
• Ģenerēt pilnu mērķarhitektūras dokumentu tieši no SSOT
• Pārlūkot dokumenta skatus un metamodeli
• Verificēt servera identitāti un uzticamību (MCPF trust framework)

9.2 Kā pieslēgties

MCP serveris ir pieejams adresē:

https://llm.kis.gov.lv/mcp

Pieslēgšanās no Claude.ai: Settings → Connectors → Add → ievadiet URL.

---

10) MCP autentifikācija

MCP serveris atbalsta trīs autentifikācijas metodes, kas var darboties vienlaicīgi (AUTH_MODE=both):

1. Statiskais Bearer tokens — vienkārša fiksēta atslēga
2. OAuth 2.1 Authorization Code + PKCE — interaktīva pieeja (Claude Desktop, pārlūkprogramma)
3. OAuth 2.0 client_credentials — mašīna-pret-mašīnu (API, skripti)

10.1 Statiskais Bearer tokens (vienkāršā pieeja)

Iestatiet .env:

AUTH_REQUIRED=true
AUTH_MODE=static          # vai "both", lai darbotos visi veidi
STATIC_BEARER_TOKEN=my-secret-token-here

Pieprasījuma piemērs:

curl -H "Authorization: Bearer my-secret-token-here" \
     http://localhost:8787/mcp

Šī metode ir piemērota iekšējai testēšanai un vienkāršiem integrācijas gadījumiem.

10.2 OAuth 2.1 — Authorization Code + PKCE (Claude Desktop)

Šo plūsmu automātiski izmanto Claude Desktop un citi MCP klienti, kas atbalsta OAuth 2.1. Serveris implementē pilnu MCP autorizācijas specifikāciju:

• RFC 9728 — Protected Resource Metadata (/.well-known/oauth-protected-resource)
• RFC 8414 — Authorization Server Metadata (/.well-known/oauth-authorization-server)
• RFC 7591 — Dynamic Client Registration (/register)
• PKCE S256 — obligāts drošības mehānisms

Konfigurācija (.env)

AUTH_REQUIRED=true
AUTH_MODE=both
SERVER_PUBLIC_URL=https://llm.kis.gov.lv:8787

# Pieteikšanās dati autorizācijas lapā
OAUTH_LOGIN_USERNAME=admin
OAUTH_LOGIN_PASSWORD=change-me

Pieslēgšanās no Claude Desktop

1. Claude Desktop → Settings → Connectors → Add
2. Ievadiet MCP servera URL: https://llm.kis.gov.lv:8787/mcp
3. Claude automātiski atklās OAuth galapunktus un atvērs pieteikšanās lapu pārlūkprogrammā
4. Ievadiet OAUTH_LOGIN_USERNAME / OAUTH_LOGIN_PASSWORD
5. Pēc autorizācijas Claude saņem JWT tokenu un izmanto to turpmākajos pieprasījumos

Plūsmas secība (tehniski)

Claude Desktop                        MCP Server
     │                                     │
     ├── POST /mcp (bez tokena) ──────────►│
     │◄── 401 + WWW-Authenticate ─────────┤
     │                                     │
     ├── GET /.well-known/                 │
     │    oauth-protected-resource ───────►│
     │◄── { authorization_servers: [...] } │
     │                                     │
     ├── GET /.well-known/                 │
     │    oauth-authorization-server ─────►│
     │◄── { endpoints, PKCE, ... }         │
     │                                     │
     ├── POST /register ─────────────────►│
     │◄── { client_id, client_secret }     │
     │                                     │
     ├── 🌐 Opens browser → /authorize ──►│
     │    (user logs in with credentials)  │
     │◄── 302 redirect with ?code=... ────┤
     │                                     │
     ├── POST /token (code + PKCE) ──────►│
     │◄── { access_token, refresh_token }  │
     │                                     │
     ├── POST /mcp + Bearer token ────────►│
     │◄── MCP response ──────────────────┤

10.3 OAuth 2.0 — client_credentials (mašīna-pret-mašīnu)

Skriptiem un API integrācijām, kas neizmanto pārlūkprogrammu.

Konfigurācija (.env)

OAUTH_CLIENT_ID=mcp-service-account
OAUTH_CLIENT_SECRET=change-me-to-a-strong-secret

Tokena iegūšana

# 1. Iegūt JWT tokenu
TOKEN=$(curl -s -X POST https://llm.kis.gov.lv:8787/token \
  -d grant_type=client_credentials \
  -d client_id=mcp-service-account \
  -d client_secret=change-me-to-a-strong-secret \
  | jq -r .access_token)

# 2. Lietot tokenu MCP pieprasījumos
curl -H "Authorization: Bearer $TOKEN" \
     https://llm.kis.gov.lv:8787/mcp

Tokens ir derīgs 1 stundu (3600 s). Pēc termiņa beigām iegūstiet jaunu.

10.4 Galapunkti

Galapunkts	Metode	Auth	Apraksts
/health	GET	Nē	Veselības pārbaude
/.well-known/oauth-protected-resource	GET	Nē	RFC 9728 — resursa metadati
/.well-known/oauth-authorization-server	GET	Nē	RFC 8414 — autorizācijas servera metadati
/.well-known/jwks.json	GET	Nē	Publiskā atslēga JWT verifikācijai
/register	POST	Nē	RFC 7591 — klienta dinamiskā reģistrācija
/authorize	GET/POST	Nē	Autorizācijas lapa (login + consent)
/token	POST	Nē	Tokenu izsniegšana (auth code, client_credentials, refresh)
/mcp	POST/GET/DELETE	Jā	MCP servera galapunkts

10.5 AUTH_MODE vērtības

Vērtība	Apraksts
both (noklusējums)	Pieņem statisko tokenu, OAuth JWT un auth code tokenu
static	Tikai statiskais Bearer tokens
jwks	Tikai OAuth/OIDC JWT (validēts ar JWKS)

10.6 Ārējais identitātes nodrošinātājs (neobligāts)

Ja izmantojat ārēju IDP (Auth0, Keycloak, Azure AD) papildus iebūvētajam OAuth:

OAUTH_JWKS_URL=https://your-idp/.well-known/jwks.json
OAUTH_ISSUER=https://your-idp/
OAUTH_AUDIENCE=your-api-audience

---

11) Darba kārtība (ieteicamais process)

1. Veic izmaiņas reģistros (registers/)
2. Ja vajag — koriģē struktūru skatos (views/)
3. Ģenerē dokumentu (npm run gen:doc vai generate_document caur MCP)
4. Palaid QA (tools/qa/)
5. Commit

---

12) Papildu materiāli

• docs/MCP.md — MCP servera dokumentācija (rīku apraksti, lietošanas scenāriji, piemēri)
• docs/TRACEABILITY.md — izsekojamība starp sākotnējo dokumentu, reģistriem un ģenerēto rezultātu
• docs/REGENERATION.md — regenerācijas procedūra un noteikumi