Skip to content

Operating visual canon (roles, decisions, and architecture)

Objective

Define one single reference sheet for technical and non-technical audiences covering operational flows, decision gates, and layered architecture.

1. Master layer map

flowchart TB
  U[Users\ncitizens | SMEs/business | financial entities | insurers | multi-trade advisory firms | public staff | employee | partner | promoter | investor | external collaborator | public service | administrations | autonomous regions | ministries | senates | provincial councils | municipalities | European states (EuroGroup) | universities and study centers | healthcare centers | sports centers | industry | social | political] --> X[UX interface\nportal | chatbot | ops panel]
  X --> R[Reasoning\nLLM + documentary RAG + auditable templates]
  R --> D[Data and governance\nordinances | BOP | BOE | case files | audit]
  D --> I[Atlantyqa infrastructure\nMicroK8s | GitOps | O11y | security | local GPU]
  I --> E[Evidence and continuous improvement\nlogs | metrics | runbooks | feedback]

2. Canonical human decision graph (HILT)

flowchart LR
  A[Request/action] --> B{Risk}
  B -->|Low| C[Guided execution]
  B -->|Medium| D[Evidence review]
  B -->|High or Critical| E[Mandatory HILT]
  D --> F{Contract compliant}
  E --> F
  F -->|Yes| G[Apply change]
  F -->|No| H[Fix and revalidate]
  G --> I[Record evidence and decision]
  H --> A

3. Audience experience mindmap

mindmap
  root((Atlantyqa Universe))
    Citizens
      mobile first
      plain language
      short steps
      source citation
    SMEs and business
      SLA
      compliance
      operations panel
      guided support
    Financial entities and insurers
      regulatory compliance
      controlled risk
      decision traceability
      service continuity
    Multi-trade advisory firms
      multi-client flow
      documentary evidence
      repeatable processes
      specialized support
    Public staff
      traceability
      operational checklist
      HILT decision
      exportable audit
    Public service and administrations
      compliance evidence
      auditable processes
      traceable decisions
      service continuity
    Ministries, senates, and provincial councils
      multi-level governance
      regulatory evidence
      inter-institutional coordination
      administrative continuity
    Autonomous regions and European states (EuroGroup)
      territorial alignment
      regulatory interoperability
      indicator comparability
      cross-border cooperation
    Municipalities
      frequent procedures
      citizen support
      regulatory guidance
      response-time metrics
    Universities and study centers
      learning pathways
      guided labs
      digital skills
      academic evidence
    Healthcare centers
      operational clarity
      safety-first posture
      traceable usage
      visible protocols
    Sports centers
      simple operations
      service and schedule flow
      clear communication
      fast support
    Industry
      operational reliability
      process integration
      risk control
      lifecycle efficiency
    Social and political
      transparency
      explainability
      participatory governance
      explicit human decisions
    Employee
      daily delivery
      task status
      operational evidence
      role-based support
    Partner
      milestone status
      shared risk
      continuity decisions
      executive visibility
    Promoter
      roadmap and deliverables
      verifiable progress
      risks and mitigation
      institutional narrative
    Investor
      adoption indicators
      risk and compliance
      execution evidence
      growth horizon
    External collaborator
      guided onboarding
      limited scope
      permission controls
      mentor approval
    Pre-sales and reseller
      clear proposal
      profile-based offer
      scope validation
      delivery handoff
    Communications
      consistent narrative
      approved messaging
      reputational control
      public traceability
    Support and user care
      fast resolution
      knowledge base
      risk-based escalation
      verifiable closure
    Developers
      incremental delivery
      local testing
      green CI
      change evidence
    Coordinators and leaders
      prioritization
      dependency management
      HILT decisions
      KPI follow-up
    Education and talent
      101 path
      guided lab
      reproducible practice
      learning evidence
    Ops and architecture
      GitOps
      layered FSM
      observability
      safe rollback

4. Documentation non-duplication contract

  1. This page is the canonical source for visual architecture and decision flow.
  2. portal/global-vision-role-based-experience.en.md expands role and profile segmentation.
  3. portal/human-agent-interaction-model.en.md details the human-machine operating contract.
  4. internal/microk8s-runtime-audience-views.en.md contains deep internal runtime views.
  5. If there is narrative conflict, this canon prevails and other pages are corrected via PR.

5. Minimum output by audience

Audience Main entry point Minimum output Value proof
Citizens mobile webapp guided answer + source task time and clarity
SMEs/business service portal status, SLA, next action lower operational friction
Financial entities/insurers regulated portal risk control + compliance + evidence continuity and trust
Advisory firms (multi-trade) professional panel case file + checklist + traceability productivity and fewer errors
Public staff authenticated portal checklist + draft + evidence fewer repetitive errors
Public service/administrations/municipalities institutional portal traceability + compliance + evidence better service and faster resolution
Ministries/senates/provincial councils institutional panel regulatory control + decision + evidence coordination and operational legitimacy
Autonomous regions/European states (EuroGroup) multi-level panel regulatory alignment + indicators + evidence territorial and European governance
Employee work panel status + priority + next action delivery continuity
Partner executive view milestones + risk + decision strategic alignment
Promoter program panel roadmap + evidence + deviations enabling execution
Investor trust panel KPI + risk + compliance investment confidence
External collaborator onboarding + task board scoped access + checklist + approval safe collaboration
Pre-sales/reseller commercial hub + trust pack proposal + scope + handoff conversion and continuity
Support/user care support desk ticket + diagnosis + action mean time to resolution
Communications narrative hub approved message + evidence institutional coherence
Developers VSCode/CLI + PR tested change + CI evidence delivery quality
Coordinators/leaders executive/operations panel decision + priority + follow-up focus and governance
Universities/study centers learning path validated practice + report adoption and continuity
Healthcare/sports centers operations panel clear action + status + escalation service continuity
Industry lifecycle panel alert + action + record operational stability
Social/political governance view decision + evidence + explanation trust and legitimacy
Ops/tech runbooks + CLI logs, artifacts, rollback lifecycle reliability

6. Local-first validation usage

  1. Validate UX narratives and flows: python3 scripts/verify/citizen_hmi_ux_guard.py
  2. Validate role routing: python3 scripts/verify/citizen_role_routing_contract_guard.py
  3. Validate RAG citation and audit template: python3 scripts/verify/rag_citation_audit_template_guard.py
  4. Run local UAT battery: bash scripts/proxmox/local_uat_battery.sh --env-file env.dev.local