Valsts-Pirmkods/Architecture-as-Code
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

KISC arch init

Browse Source
This commit is contained in:
rg4444
2026-10-11 14:36:51 +03:00
commit 8fb6c52e44
89 changed files with 10931 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

409
ikt-arh-kultura-valodu-tehnologijas/README.md Normal file
View File

@@ -0,0 +1,409 @@
# 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