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:

```md
`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:

```bash
cd mcp
npm install
```

### 7.3 Dokumenta ģenerēšana (komandrinda)

No repozitorija saknes:

```bash
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:

```bash
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](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`:

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

Pieprasījuma piemērs:

```bash
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)

```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)

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

#### Tokena iegūšana

```bash
# 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:

```env
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](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