Š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):

Statiskais Bearer tokens — vienkārša fiksēta atslēga
OAuth 2.1 Authorization Code + PKCE — interaktīva pieeja (Claude Desktop, pārlūkprogramma)
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

Claude Desktop → Settings → Connectors → Add
Ievadiet MCP servera URL: https://llm.kis.gov.lv:8787/mcp
Claude automātiski atklās OAuth galapunktus un atvērs pieteikšanās lapu pārlūkprogrammā
Ievadiet OAUTH_LOGIN_USERNAME / OAUTH_LOGIN_PASSWORD
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)

Veic izmaiņas reģistros (registers/)
Ja vajag — koriģē struktūru skatos (views/)
Ģenerē dokumentu (npm run gen:doc vai generate_document caur MCP)
Palaid QA (tools/qa/)
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