System Architecture¶

The Punnaraj system is organized in seven layers, each with clear responsibility boundaries.

Seven-Layer Architecture¶

┌─────────────────────────────────────────────────────────────┐
│  1. DOCTRINE LAYER                                          │
│     What we believe, how we make decisions                  │
│     (alpha_workspace, core-principles)                      │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  2. REGISTRY & INTELLIGENCE LAYER                           │
│     What exists, what state it's in                         │
│     (punnaraj-over-view, command-center)                    │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  3. CONTROL PLANE LAYER                                     │
│     Who can do what, approval gates                         │
│     (mcp-cloudflare, mcp-github, punnaraj-cloudflare-control) │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  4. OPERATIONAL CORE LAYER                                  │
│     What runs the system, API endpoints                     │
│     (Punnaraj-api, punnaraj-mcp)                           │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  5. SECURITY LAYER                                          │
│     Secrets, credentials, access control                    │
│     (magga-940-secretman)                                   │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  6. DATA LAYER                                              │
│     Persistent storage, schemas                             │
│     (family-vault, D1 databases)                            │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  7. GOVERNANCE & CONTINUITY LAYER                           │
│     Policies, succession, family operations                 │
│     (pun-policy, continuity, punnaraj-family)              │
└─────────────────────────────────────────────────────────────┘

Key Principles¶

Separation of Concerns¶

Doctrine ≠ Operations ≠ Security ≠ Governance
Each layer can be audited independently
Failure in one doesn't cascade to all
Future variations possible without rewriting core

Three-Space Design¶

Public Space (docs/ branches) - Baseline assumptions - Principles, processes, reproducible knowledge - Safe to share, open to review

Private Space (encrypted, separate storage) - Family identity, personal documents, financial details - Referenced by ID only from public space - Never in Git repositories

Processing Space (inbox → normalized → reviewed → promoted) - Raw inputs from conversation summaries - Contradiction detection - Validation against standards - Promotion to Public or Private once verified

Authority Model¶

⚠️ CLARIFICATION NEEDED on overlapping authorities (see Governance section).

Current state: - Registry Authority (punnaraj-over-view) — "which repo does what" - Operational Authority (Punnaraj-api) — "what runs right now" - Control Authority (mcp-cloudflare, mcp-github) — "what changes are allowed" - Local Authority (zero_workspace, genesis-bootstrap) — "what I decide on my machine"

When they conflict → document the conflict, don't hide it.

Data Flow¶

Human Intent / External Events
           ↓
Evidence Collection (Observation)
           ↓
Control Planes (Policy + Approval)
           ↓
Operations (API execution)
           ↓
Security (Credential injection)
           ↓
Data Storage (Audit log + records)
           ↓
Intelligence Surface (command-center dashboard)
           ↓
Human Review & Decision

Control Plane Pattern (MAGGA Reference)¶

The MAGGA-114 Cloudflare Control is the reference implementation for how all external systems should be accessed:

Human / AI / Service
         ↓
    Gateway (Identity + Auth)
         ↓
   Policy Engine (What's allowed?)
         ↓
  External API (Cloudflare/GitHub/etc)
         ↓
   Audit Log (Every action recorded)

Safety defaults: - Agent doesn't hold secrets (managed separately) - GET defaults allowed; writes default deny - Dry-run before apply - Staging sandbox only - High-risk actions (delete) require approval - Every response includes: audit trail, risk level, approval status

This pattern should replicate for GitHub, Google, Telegram, etc.

Data Orchestration Evolution¶

The accepted direction is to build mcp-obsidian as the first complete data-lifecycle vertical slice, then extract the provider-independent contracts into a Data Orchestrator. Command Center will remain the observability surface and later consume the orchestrator's normalized metadata, delta, replica health, and execution receipts.

Read: MCP Obsidian to Data Orchestrator

Next: Learn What Each Repository Does¶

See the Projects section for complete inventory of all 32 repositories and their roles.