Architecture Pack — Wetopi Knowledge Plane v0

1. Status

Proposed

Este Architecture Pack define la arquitectura inicial para arrancar la nueva organización documental de Wetopi.

Sustituye el enfoque anterior basado en BookStack como knowledge base.

2. Problem Statement

Wetopi necesita una única plataforma de conocimiento que funcione simultáneamente para:

• humanos;
• Hermes;
• futuros agentes ADK;
• agentes SRE;
• agentes developers;
• agentes reviewers;
• agentes curators.

La arquitectura debe evitar duplicación entre repositorios, wiki, memoria, RAG, artifacts y UI humanas.

3. Architecture Decision

La fuente de verdad será:

Git repository
+
Markdown
+
Wiki-LLM conventions

El repositorio se publicará mediante MkDocs y se indexará de forma derivada para agentes.

BookStack será retirado.

4. System Context

flowchart TB
    H[Humans]
    A[Hermes / ADK Agents]
    G[(Git: wetopi-knowledge)]
    M[MkDocs]
    D[docs.wetopi.net]
    K[wetopi-knowledge-mcp]
    I[(Knowledge Index)]
    C[Wiki Curator]
    HS[Hindsight]
    S3[(Ceph / S3 Artifacts)]

    H --> G
    A --> G
    G --> M
    M --> D
    G --> I
    I --> K
    K --> A
    HS --> A
    A --> HS
    S3 --> A
    A --> S3
    C --> G
    G --> C

5. Core Principle

Git Markdown
= Canonical Knowledge

MkDocs
= Human View

Knowledge MCP
= Agent Retrieval View

Hindsight
= Memory / Experience / Wisdom

S3
= Evidence

6. Repository Architecture

wetopi-knowledge/
│
├── README.md
├── index.md
├── AGENTS.md
├── mkdocs.yml
│
├── infrastructure/
│   ├── ovh/
│   ├── physical-nodes/
│   ├── proxmox/
│   ├── ceph/
│   └── networking/
│
├── platform/
│   ├── rke2/
│   ├── cilium/
│   ├── traefik/
│   ├── argocd/
│   ├── infisical/
│   ├── litellm/
│   ├── hindsight/
│   ├── observability/
│   └── knowledge-plane/
│
├── wetopi-app/
├── wordpress-hosting/
├── operations/
├── agents/
│
├── architecture/
├── decisions/
├── concepts/
├── investigations/
├── incidents/
├── runbooks/
├── records/
│
├── _schema/
├── _templates/
└── raw/

7. Domain Model

Infrastructure

Cosas que siguen existiendo aunque Kubernetes desaparezca:

• OVH;
• physical nodes;
• Proxmox;
• Ceph;
• L2/L3;
• BGP;
• VRRP;
• WAN;
• IPVS;
• NAT gateways.

Platform

Servicios compartidos que convierten la infraestructura en plataforma:

• RKE2;
• Cilium;
• Traefik;
• Argo CD;
• Infisical;
• LiteLLM;
• Hindsight;
• observabilidad;
• Knowledge Plane.

Wetopi App

Control plane propietario de Wetopi.

WordPress Hosting

Runtime y lifecycle de sites WordPress.

Operations

Runbooks, incidentes e investigaciones.

Agents

Harnesses, perfiles, skills, memoria, contracts y flota.

8. Document Ontology

graph LR
    OBJ[OBJ Objective]
    INV[INV Investigation]
    INC[INC Incident]
    ADR[ADR Decision]
    DES[DES Design]
    SVC[SVC Service]
    RUN[RUN Runbook]
    REC[REC Record]
    ART[ART Artifact]
    CON[CON Concept]

    OBJ -->|PRODUCES| INV
    INV -->|INVESTIGATES| SVC
    INV -->|EVIDENCE| ART
    INV -->|DERIVED_FROM| INC
    INV -->|PRODUCES| ADR
    ADR -->|GOVERNS| SVC
    ADR -->|AFFECTS| DES
    RUN -->|OPERATES| SVC
    REC -->|AFFECTS| SVC
    CON -->|RELATED_TO| SVC

9. Frontmatter Contract

Required

---
id: <GLOBAL-ID>
type: <document-type>
title: <title>
status: <status>
domain: <domain>
created_at: YYYY-MM-DD
last_verified: YYYY-MM-DD
owners:
  - <owner>
---

Optional relations

depends_on: []
related: []
governed_by: []
affects: []
derived_from: []
evidence: []
runbooks: []
supersedes: []
aliases: []

10. Status Model

General:

draft
proposed
active
deprecated
superseded
archived

ADR:

draft
proposed
accepted
deprecated
superseded
rejected

Runbook:

draft
active
deprecated

11. Wiki-LLM Integration

Hermes incluye:

~/skills/research/llm-wiki

v2.1.0.

flowchart LR
    SRC[Source]
    ING[llm-wiki ingest]
    RAW[raw/ or S3]
    SYN[Synthesis]
    MD[Wiki Markdown]
    LINT[llm-wiki lint]
    PR[Pull Request]

    SRC --> ING
    ING --> RAW
    ING --> SYN
    SYN --> MD
    MD --> LINT
    LINT --> PR

Extensiones Wetopi:

• schema propio;
• IDs globales;
• relaciones tipadas;
• multiagente;
• Git workflow;
• authority/status;
• lifecycle;
• integración Hindsight;
• artifacts externos;
• Knowledge MCP.

12. Multi-Agent Write Path

sequenceDiagram
    participant Agent
    participant Worktree
    participant Wiki as llm-wiki
    participant CI
    participant Curator
    participant Git

    Agent->>Worktree: create branch/worktree
    Agent->>Wiki: ingest/update pages
    Wiki->>Worktree: Markdown + wikilinks
    Agent->>CI: open PR
    CI->>CI: schema validation
    CI->>CI: llm-wiki lint
    CI->>CI: graph validation
    CI->>CI: mkdocs build --strict
    CI->>Curator: review if required
    Curator->>Git: merge

13. Read Path for Agents

sequenceDiagram
    participant Agent
    participant MCP as Knowledge MCP
    participant IDX as Index
    participant Git
    participant HS as Hindsight

    Agent->>HS: recall task/context
    HS-->>Agent: facts + experience + source IDs
    Agent->>MCP: knowledge_search(query)
    MCP->>IDX: hybrid search
    IDX-->>MCP: ranked nodes/docs
    MCP-->>Agent: context + IDs
    Agent->>MCP: knowledge_read(ADR/SVC/RUN)
    MCP->>Git: resolve canonical content
    Git-->>MCP: document
    MCP-->>Agent: authoritative source

Principio:

Recall first. Retrieve authoritative sources when needed.

14. Knowledge MCP Architecture

flowchart TB
    G[(Git Markdown)]
    P[Markdown Parser]
    FM[Frontmatter Parser]
    WL[Wikilink Resolver]
    GI[Git Metadata]
    GR[Graph Builder]
    FTS[FTS5]
    VE[Embeddings]
    DB[(SQLite / Derived Index)]
    MCP[wetopi-knowledge-mcp]
    A[Agents]

    G --> P
    G --> FM
    G --> WL
    G --> GI

    P --> GR
    FM --> GR
    WL --> GR
    GI --> GR

    P --> FTS
    P --> VE

    GR --> DB
    FTS --> DB
    VE --> DB

    DB --> MCP
    MCP --> A

15. MCP API v0

knowledge_search(query, filters?)
knowledge_read(id_or_path, section?)
knowledge_related(id, relation?, depth?)
knowledge_graph(ids, depth?)
knowledge_tree(path?)
knowledge_grep(pattern, scope?)

Filtros:

domain
type
status
owner
service
date
authority

16. Retrieval Ranking

score =
 lexical
 + semantic
 + graph_proximity
 + authority
 + freshness
 - stale_penalty
 - superseded_penalty

El índice debe favorecer documentos canónicos y actuales.

17. Hindsight Boundary

Hindsight no será el índice documental.

Debe retener:

facts
experiences
observations
learned knowledge
relations
timestamps
confidence
source pointers

No debe retener como memoria documentos completos o grandes reports.

18. Hindsight → Wiki Promotion

flowchart LR
    O[Observations]
    E[Experiences]
    H[Hindsight]
    C[Curator]
    W[Canonical Wiki]

    O --> H
    E --> H
    H --> C
    C -->|repeated / validated knowledge| W

Candidatos a promoción:

• patrones repetidos;
• conocimiento de alto impacto;
• conclusión reutilizable;
• decisión estable;
• contradicción resuelta;
• experiencia operacional generalizable.

19. Artifact Boundary

flowchart LR
    A[Agent]
    S3[(Ceph S3)]
    SUM[summary.md]
    MAN[manifest.yaml]
    W[Wiki]

    A --> S3
    S3 --> SUM
    S3 --> MAN
    SUM --> W
    MAN --> W

Raw grande permanece en S3.

20. Agent Documentation Contract

Al terminar una tarea:

ARTIFACT?
→ S3

REUSABLE KNOWLEDGE?
→ Wiki

DECISION?
→ ADR / RFC

OPERATIONAL EVENT?
→ REC / INC

MEMORY?
→ Hindsight

RELATIONS?
→ graph metadata

El harness debe ejecutar este checklist.

21. BookStack Decommission Decision

Decision

BookStack no forma parte del Knowledge Plane objetivo.

Reason

Introduce una segunda fuente documental con:

• almacenamiento propio;
• API propia;
• lifecycle propio;
• potencial duplicación;
• peor integración Git;
• menor compatibilidad directa con agentes;
• necesidad de sincronización.

Migration principle

BookStack
   ↓ export
Markdown
   ↓ normalize
Wiki schema
   ↓ PR
wetopi-knowledge

22. BookStack Cleanup Runbook

Phase A — Inventory

El agente debe buscar:

bookstack
book.wetopi.net
platform-bookstack
BOOKSTACK_

en todos los repositorios y sistemas permitidos.

Debe generar una investigación, por ejemplo:

INV-BOOKSTACK-REMOVAL

que recoja:

• referencias encontradas;
• recursos Kubernetes;
• secrets;
• URLs;
• manifests;
• repos;
• contenido;
• dashboards;
• monitoring;
• dependencias.

Phase B — Preserve Knowledge

Exportar contenido y clasificar cada elemento:

KEEP
MERGE
SUPERSEDE
DELETE

KEEP y MERGE se migran a wetopi-knowledge.

Phase C — Remove Integrations

Eliminar:

• referencias en Markdown;
• enlaces;
• agent prompts;
• harness config;
• env vars;
• secrets;
• dashboards;
• alerts;
• health checks;
• CI jobs.

Phase D — Remove Runtime

Eliminar, cuando ya no haya contenido único:

• Argo CD Application;
• Helm values;
• Kubernetes manifests;
• Deployment/StatefulSet;
• Service;
• Ingress/Gateway;
• DNS;
• MariaDB asociada si es exclusiva;
• PVC/RBD asociado después del backup;
• monitoring específico.

Phase E — Verify

Debe cumplirse:

global search → no active BookStack refs
DNS → removed
Argo → removed
Kubernetes → removed
Infisical → secret removed
docs → migrated
backup → retained according to policy

23. BookStack Safety Gate

El agente no debe destruir DB/PVC hasta verificar:

[ ] export complete
[ ] migrated knowledge merged
[ ] backup validated
[ ] no unique content remains
[ ] rollback point exists

24. MkDocs Publishing

flowchart LR
    M[Merge main]
    CI[CI]
    L[llm-wiki lint]
    S[Schema Lint]
    B[mkdocs build --strict]
    P[Publish]
    D[docs.wetopi.net]

    M --> CI
    CI --> L
    CI --> S
    CI --> B
    B --> P
    P --> D

25. Validation Pipeline

Checks previstos:

duplicate IDs
invalid frontmatter
invalid document type
broken wikilinks
broken structured relations
orphan pages
MkDocs strict errors
forbidden secrets
oversized files
BookStack references after migration

Algunos pueden comenzar como warning y convertirse después en blocking.

26. Proposed Repo Files

Bootstrap:

README.md
AGENTS.md
mkdocs.yml

_schema/
  frontmatter.md
  relations.md
  document-types.md
  naming.md

_templates/
  service.md
  concept.md
  adr.md
  investigation.md
  runbook.md
  record.md

platform/knowledge-plane/
  overview.md
  architecture.md
  operations.md

decisions/
  ADR-0001-git-markdown-source-of-truth.md
  ADR-0002-remove-bookstack.md
  ADR-0003-hindsight-memory-boundary.md
  ADR-0004-knowledge-mcp-derived-index.md
  ADR-0005-agents-contribute-via-pr.md

27. Initial ADR Set

ADR-0001

Git + Markdown is the canonical Wetopi knowledge source.

ADR-0002

BookStack is removed from the target architecture.

ADR-0003

Hindsight stores memory/experience, not canonical documents.

ADR-0004

Knowledge MCP indexes derived state and can be rebuilt.

ADR-0005

Agents contribute through branch/worktree + PR.

28. Implementation Phases

Phase 0 — Freeze

• freeze new BookStack content;
• declare Git/Markdown target;
• create migration objective.

Phase 1 — Bootstrap Wiki

• create repository;
• install schema;
• configure Wiki-LLM path;
• create AGENTS.md;
• create templates;
• configure MkDocs.

Phase 2 — Migrate

• export BookStack;
• ingest existing docs;
• normalize;
• create IDs;
• add wikilinks;
• merge.

Phase 3 — Publish

• CI;
• mkdocs build --strict;
• deploy docs.wetopi.net;
• validate navigation/search.

Phase 4 — Agent Integration

• Hermes Wiki-LLM contract;
• worktrees;
• PR policy;
• documentation closure step;
• Wiki Curator.

Phase 5 — Knowledge MCP v0

• Markdown parser;
• SQLite;
• FTS5;
• graph;
• MCP tools.

Phase 6 — Semantic Retrieval

• embeddings;
• semantic relations;
• hybrid ranking;
• context packs.

Phase 7 — Hindsight Loop

• source pointers;
• curator;
• promotion candidates;
• contradiction workflow.

Phase 8 — BookStack Destruction

Sólo después de migración y verificación.

29. Backlog v0

P0

• [ ] Create wetopi-knowledge
• [ ] Configure MkDocs
• [ ] Add AGENTS.md
• [ ] Define frontmatter schema
• [ ] Define relations
• [ ] Define ID namespaces
• [ ] Configure Hermes llm-wiki
• [ ] Freeze BookStack
• [ ] Inventory BookStack content and references
• [ ] Migrate unique BookStack content
• [ ] Remove BookStack references
• [ ] Remove BookStack runtime

P1

• [ ] CI lint
• [ ] Wiki Curator
• [ ] agent worktree workflow
• [ ] documentation contract in Hermes harness
• [ ] artifact manifest
• [ ] Hindsight source-pointer convention

P2

• [ ] Knowledge Index
• [ ] SQLite schema
• [ ] graph builder
• [ ] FTS5
• [ ] Knowledge MCP
• [ ] hybrid retrieval

P3

• [ ] embeddings
• [ ] semantic duplicate detection
• [ ] automated synthesis suggestions
• [ ] graph visualization
• [ ] retrieval telemetry
• [ ] context compilation optimization

30. Definition of Done — Bootstrap

[ ] Git repo is canonical
[ ] docs.wetopi.net builds from it
[ ] Hermes llm-wiki works against a worktree
[ ] schema exists
[ ] IDs exist
[ ] wikilinks work
[ ] PR validation works
[ ] BookStack contains no unique unmigrated knowledge
[ ] BookStack runtime is removed or only awaiting final destruction gate
[ ] Hindsight uses source pointers

31. Non-Goals v0

No intentar inicialmente:

• graph DB distribuido;
• reemplazar Hindsight;
• almacenar todos los artifacts en Git;
• inferir automáticamente todas las relaciones;
• permitir escritura directa a main;
• indexar cada byte de logs;
• crear una ontología perfecta;
• desplegar Neo4j/Qdrant/OpenSearch sin necesidad medida.

32. Architecture Fitness Functions

La arquitectura debe seguir siendo válida si:

1. se elimina por completo el índice MCP;
2. se reconstruye a partir de Git;
3. se cambia MkDocs por otro renderer;
4. se cambia el backend del índice;
5. un agente desaparece;
6. Hindsight no está disponible temporalmente.

En todos esos casos:

El conocimiento canónico sigue existiendo en Markdown/Git.

33. Final Architecture

flowchart TB
    subgraph Canonical["Canonical Knowledge"]
      G[(Git: wetopi-knowledge)]
    end

    subgraph Human["Human Interface"]
      MK[MkDocs]
      WEB[docs.wetopi.net]
    end

    subgraph AgentRetrieval["Agent Retrieval"]
      IDX[(Graph + FTS + Vectors)]
      MCP[wetopi-knowledge-mcp]
    end

    subgraph Learning["Operational Learning"]
      HS[Hindsight]
      CUR[Wiki Curator]
    end

    subgraph Evidence["Evidence"]
      S3[(Ceph / S3)]
    end

    subgraph Agents["Execution"]
      HERMES[Hermes]
      ADK[ADK Agents]
    end

    G --> MK --> WEB
    G --> IDX --> MCP
    MCP --> HERMES
    MCP --> ADK

    HERMES --> HS
    ADK --> HS
    HS --> CUR
    CUR --> G

    HERMES --> S3
    ADK --> S3
    S3 --> CUR

34. Architecture Motto

Git Markdown is the knowledge.
MkDocs is the human view.
Knowledge MCP is the agent view.
Hindsight is the memory.
S3 is the evidence.