Skip to content

CLARISSA โ€“ Architecture Decision Records (ADR Index)

Purpose of ADRs

This directory contains Architecture Decision Records (ADRs) for CLARISSA. ADRs document significant architectural decisions, their rationale, and consequences over time.

How to Read These ADRs

  • Accepted ADRs define the current baseline.
  • Proposed ADRs indicate active design discussions.
  • Superseded ADRs remain for historical context.

ADR List

Core Architecture

ADR Title Status
001 Physics-Centric, Simulator-in-the-Loop Architecture Accepted
002 Separation of Reasoning, Learning, and Governance Accepted
003 CLARISSA-Native Simulation Kernel Accepted
009 Multi-Stage NLP Translation Pipeline Proposed
011 OPM Flow Integration Accepted

Infrastructure & CI/CD

ADR Title Status
006 Noise-free CI Artifact Directories Accepted
007 CI as an Observability Layer Accepted
012 Container Registry & K8s Strategy Accepted
015 LLM CI Notifications Accepted
016 Runner Load Balancing Accepted
017 GDrive Folder Structure Accepted
019 Billing Folder Structure (Contractors) Accepted

Repository & Process

ADR Title Status
005 Single Repository Until Architecture Stabilizes Accepted
008 Governance Signals vs Enforcement Accepted
010 Project Renaming to CLARISSA Accepted
013 Internationalization Architecture Accepted
014 LLM Document Merge Accepted
018 GitLab-Native Project Management Workflow Accepted

Portal & Advanced Architecture

ADR Title Status
020 Portal Vision Accepted
021 Portal System Security Accepted
022 Portal Software Architecture Accepted
023 Portal Observability Accepted
024 CLARISSA Core Architecture Accepted
025 LLM Integration Strategy Accepted
026 Testing Strategy Accepted
027 Bidirectional Repo Sync Accepted
028 ๐ŸŽค Voice Input Architecture Accepted
031 Portal Location Strategy Accepted

Superseded

ADR Title Status Superseded By
004 Dual-Simulator Strategy Superseded ADR-001

ADR Coverage Map

Architectural Aspect ADR
Physics-centric learning ADR-001
Separation of roles (LLM/RL/Governance) ADR-002
Native simulation kernel ADR-003
NLP translation pipeline ADR-009
OPM Flow integration ADR-011
Repository strategy ADR-005
CI hygiene & developer experience ADR-006
CI observability & reporting ADR-007
Governance signals & enforcement ADR-008
Container & K8s strategy ADR-012
Internationalization ADR-013
LLM document processing ADR-014
CI notifications ADR-015
Runner load balancing ADR-016
GDrive organization ADR-017
Billing folders (contractors) ADR-019
Development workflow ADR-018
Portal architecture ADR-020, ADR-021, ADR-022, ADR-023
CLARISSA core design ADR-024
LLM strategy ADR-025
Testing & validation ADR-026
Repository sync ADR-027
Voice interface ๐ŸŽค ADR-028

Cross-References

Architecture Diagrams

  • docs/architecture/diagrams/*.mmd โ€” Mermaid sources
  • architecture/layered-architecture.puml โ€” PlantUML overview
  • architecture/learning-dialectic.puml โ€” Learning flow

Conference Artifacts

  • conference/abstract.md โ€” CLARISSA abstract
  • conference/ijacsa-2026/ โ€” IJACSA 2026 paper submission

Implementation

  • src/clarissa/agent/ โ€” Agent core (ADR-002)
  • src/clarissa/governance/ โ€” Governance policy (ADR-002, ADR-008)
  • src/clarissa_kernel/ โ€” Native kernel (ADR-003)
  • docs/simulators/adapter_matrix.md โ€” Simulator backends (ADR-001)

Creating New ADRs

Use the template: ADR-000-template.md

Naming convention: ADR-NNN-short-descriptive-title.md

When to create an ADR: - Introducing a new architectural component - Changing responsibilities or boundaries - Making technology choices with long-term impact - Establishing patterns or conventions