# SophiaClaw Documentation Architecture Plan

> **Purpose**: Comprehensive documentation architecture for open sourcing SophiaClaw as a frontier model provider  
> **Generated**: 2026-03-11  
> **Source**: Algorithm Inventory (48 components across 9 categories)  
> **Target**: Open source release with full transparency and community contribution support

---

## 1. Documentation Structure

```
docs/
├── requirements/
│   ├── SYSTEM_REQUIREMENTS.md          # Hardware, OS, dependencies
│   ├── RFC-001-gateway-architecture.md # Gateway design decisions
│   ├── RFC-002-memory-backend.md       # Memory backend abstraction
│   ├── RFC-003-plugin-security.md      # Plugin isolation model
│   ├── RFC-004-media-pipeline.md       # Media understanding pipeline
│   └── rfc-template.md                 # Template for future RFCs
│
├── algorithms/
│   ├── core-infrastructure/
│   │   ├── 001-circuit-breaker.md
│   │   ├── 002-device-pairing.md
│   │   ├── 003-log-integrity.md
│   │   ├── 004-dns-sd-discovery.md
│   │   ├── 005-fs-permission-inspector.md
│   │   ├── 006-command-approval.md
│   │   ├── 007-ssrf-protection.md
│   │   └── 008-abort-pattern-matching.md
│   │
│   ├── governance/
│   │   ├── 009-security-audit-engine.md
│   │   ├── 010-dangerous-config-flags.md
│   │   ├── 011-scope-implication.md
│   │   └── 012-session-key-normalization.md
│   │
│   ├── security/
│   │   ├── 013-constant-time-comparison.md
│   │   ├── 014-credential-encryption.md
│   │   ├── 015-encrypted-json-storage.md
│   │   ├── 016-windows-acl.md
│   │   └── 017-audit-log-aggregator.md
│   │
│   ├── gateway-network/
│   │   ├── 018-auth-router.md
│   │   ├── 019-rate-limiter.md
│   │   ├── 020-client-ip-resolution.md
│   │   ├── 021-connection-manager.md
│   │   └── 022-node-registry.md
│   │
│   ├── memory-search/
│   │   ├── 023-fallback-manager.md
│   │   ├── 024-memory-index.md
│   │   ├── 025-qmd-backend.md
│   │   └── 026-backend-config.md
│   │
│   ├── agent-management/
│   │   ├── 027-agent-scope.md
│   │   ├── 028-api-key-rotation.md
│   │   ├── 029-auth-cooldown.md
│   │   ├── 030-bash-registry.md
│   │   └── 031-apply-patch.md
│   │
│   ├── ui-ux/
│   │   ├── 032-terminal-ui.md
│   │   ├── 033-burst-coalescer.md
│   │   ├── 034-osc8-hyperlinks.md
│   │   └── 035-gateway-chat.md
│   │
│   ├── platforms/
│   │   ├── 036-macos-appstate.md
│   │   ├── 037-macos-permissions.md
│   │   └── 038-macos-websocket.md
│   │
│   ├── plugins/
│   │   ├── 039-plugin-http-auth.md
│   │   ├── 040-channel-registry.md
│   │   ├── 041-plugin-sdk.md
│   │   └── 042-extension-entrypoint.md
│   │
│   └── media/
│       ├── 043-media-understanding.md
│       └── 044-attachment-normalizer.md
│
├── architecture/
│   ├── OVERVIEW.md                     # System architecture summary
│   ├── gateway-architecture.md         # Gateway service design
│   ├── memory-architecture.md          # Memory subsystem design
│   ├── security-architecture.md        # Security model overview
│   ├── plugin-architecture.md          # Plugin system design
│   ├── multi-tenant-design.md          # Agent scope & tenancy
│   └── data-flow/
│       ├── message-flow.md             # End-to-end message lifecycle
│       ├── approval-flow.md            # Command approval workflow
│       └── memory-write-flow.md        # Memory persistence flow
│
├── diagrams/
│   ├── internal/
│   │   ├── gateway-auth-flow.drawio    # Gateway authentication state machine
│   │   ├── device-pairing-sequence.drawio # Device pairing sequence diagram
│   │   ├── circuit-breaker-states.drawio # Circuit breaker state transitions
│   │   ├── memory-backend-failover.drawio # Memory backend failover logic
│   │   ├── plugin-isolation-model.drawio # Plugin sandbox architecture
│   │   ├── security-audit-checks.drawio # Audit engine check flow
│   │   ├── gateway-auth-router.drawio  # Auth method routing logic
│   │   ├── media-pipeline-stages.drawio # Media processing pipeline
│   │   └── agent-scope-resolution.drawio # Multi-tenant scope resolution
│   │
│   └── public/
│       ├── high-level-architecture.drawio # System overview diagram
│       ├── value-proposition.drawio    # User value flow
│       ├── deployment-topology.drawio  # Deployment scenarios
│       ├── security-boundaries.drawio  # Trust boundaries diagram
│       ├── plugin-ecosystem.drawio     # Plugin integration model
│       └── user-journey.drawio         # End-user experience flow
│
├── api/
│   ├── gateway-rpc-api.md              # Gateway WebSocket RPC methods
│   ├── plugin-sdk-api.md               # Plugin SDK reference
│   ├── channel-plugin-api.md           # Channel plugin interface
│   ├── cli-api.md                      # CLI command reference
│   ├── config-schema.md                # Configuration schema reference
│   └── openrpc-spec.json               # OpenRPC specification (auto-generated)
│
├── security/
│   ├── SECURITY_MODEL.md               # Overall security architecture
│   ├── threat-model.md                 # STRIDE threat analysis
│   ├── authentication-model.md         # AuthN/AuthZ design
│   ├── credential-storage.md           # Credential encryption details
│   ├── sandbox-model.md                # Plugin/agent sandboxing
│   ├── network-security.md             # SSRF, DNS rebinding protection
│   ├── audit-system.md                 # Audit log integrity
│   └── vulnerability-disclosure.md     # Responsible disclosure process
│
└── governance/
    ├── GOVERNANCE_MODEL.md             # Project governance structure
    ├── policy-engine.md                # Policy decision framework
    ├── rfc-process.md                  # Request for Comments process
    ├── security-committee.md           # Security review committee
    ├── contribution-guidelines.md      # How to contribute (links to root CONTRIBUTING.md)
    └── decision-records/
        ├── adr-001-gateway-mode.md     # Architecture Decision Records
        └── adr-002-memory-backend.md
```

---

## 2. Algorithm Documentation Template

Each algorithm document follows this standard template:

```markdown
# {Algorithm Name}

> **File**: `src/path/to/file.ts`  
> **Priority**: HIGH | MEDIUM | LOW  
> **Category**: core-infrastructure | governance | security | gateway-network | memory-search | agent-management | ui-ux | platforms | plugins | media  
> **Status**: draft | review | approved

---

## Overview & Purpose

{2-3 sentence summary of what this algorithm does and why it exists}

**Problem Statement**: {What problem does this solve? What happens without it?}

**Design Decisions**:

- {Key design choice 1 with rationale}
- {Key design choice 2 with rationale}
- {Key design choice 3 with rationale}

---

## Algorithm Specification

### Pseudocode
```

function AlgorithmName(inputs):
{Step-by-step algorithm in pseudocode}
return result

```

### State Machine (if applicable)

```

{state1} → {state2} ({trigger})
{state2} → {state3} ({trigger})

````

### Complexity Analysis

| Metric | Value | Notes |
|--------|-------|-------|
| Time | O(?) | {Explanation} |
| Space | O(?) | {Explanation} |
| Best Case | O(?) | {When} |
| Worst Case | O(?) | {When} |

---

## Input/Output Specifications

### Inputs

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `name` | `type` | Yes/No | `value` | Description |

### Outputs

| Return Value | Type | Description |
|--------------|------|-------------|
| `result` | `type` | Description |

### Errors/Exceptions

| Error | Condition | Recovery |
|-------|-----------|----------|
| `ErrorName` | When... | {How to handle} |

---

## Error Handling

{Detailed error handling strategy, retry logic, fallback behavior}

---

## Testing Strategy

### Unit Tests

```typescript
// Test case 1: Happy path
it('should {expected behavior}', async () => {
  // Test implementation
})

// Test case 2: Edge case
it('should handle {edge case}', async () => {
  // Test implementation
})

// Test case 3: Error case
it('should throw {error} when {condition}', async () => {
  // Test implementation
})
````

### Integration Tests

{Integration test scenarios}

### Test Coverage Target

- Lines: {X}%
- Branches: {X}%
- Functions: {X}%

---

## Security Considerations

| Threat     | Mitigation   | Status      |
| ---------- | ------------ | ----------- |
| {Threat 1} | {Mitigation} | Implemented |
| {Threat 2} | {Mitigation} | Implemented |

**Security Properties**:

- {Property 1: e.g., "Constant-time comparison prevents timing attacks"}
- {Property 2: e.g., "Input validation prevents injection"}

---

## Performance Benchmarks

| Scenario     | Throughput  | Latency (p50/p95/p99) | Notes        |
| ------------ | ----------- | --------------------- | ------------ |
| {Scenario 1} | {X} ops/sec | {X}/{X}/{X} ms        | {Conditions} |
| {Scenario 2} | {X} ops/sec | {X}/{X}/{X} ms        | {Conditions} |

**Benchmarks run on**: {Hardware specs, Node.js version}

---

## Dependencies

| Dependency | Purpose  | Version |
| ---------- | -------- | ------- |
| `module`   | Why used | ^X.Y.Z  |

---

## Related Components

- `{src/path/to/related.ts}` - {Relationship}
- `{docs/algorithms/...}` - {Related algorithm}

---

## References

- [External resource 1](url)
- [External resource 2](url)

---

## Changelog

| Date       | Version | Change                |
| ---------- | ------- | --------------------- |
| 2026-03-11 | 1.0.0   | Initial documentation |

```

---

## 3. Diagram Standards

### Internal Diagrams (`docs/diagrams/internal/`)

**Purpose**: Deep technical understanding for maintainers and contributors

**Standards**:
- **Format**: DrawIO (.drawio) with PNG exports
- **Detail Level**: Component-level interactions, data flows, state machines
- **Color Scheme**:
  - `#4A90D9` (Blue) - Core components
  - `#50C878` (Green) - External services
  - `#FFB347` (Orange) - Data stores
  - `#FF6B6B` (Red) - Security boundaries
  - `#9B59B6` (Purple) - Async processes
- **Notation**:
  - Solid arrows: Synchronous calls
  - Dashed arrows: Async/event-driven
  - Red borders: Security-critical paths
  - Dotted boxes: External trust boundaries
- **Required Diagrams**:
  - Sequence diagrams for multi-component flows
  - State machines for stateful components
  - Data flow diagrams for pipelines
  - Component interaction diagrams

**Label Convention**:
```

ComponentName
{Type}
[Key Properties]

```

---

### Public Diagrams (`docs/diagrams/public/`)

**Purpose**: High-level understanding for users, evaluators, and potential contributors

**Standards**:
- **Format**: DrawIO (.drawio) with PNG + SVG exports
- **Detail Level**: System-level architecture, user flows, value proposition
- **Color Scheme**:
  - `#2E5C8A` (Dark Blue) - SophiaClaw core
  - `#3FA958` (Dark Green) - User systems
  - `#D98E04` (Dark Orange) - Third-party integrations
  - `#B93131` (Dark Red) - Security/trust boundaries
- **Notation**:
  - Simplified component boxes (no internal details)
  - Clear user journey arrows
  - Minimal technical jargon
  - Callouts for key value props
- **Required Diagrams**:
  - High-level architecture (single page)
  - Deployment scenarios (local, cloud, hybrid)
  - User journey from pairing to daily use
  - Plugin ecosystem model
  - Security boundary overview

**Design Principles**:
- Understandable in <30 seconds
- No knowledge of internals required
- Focus on "what" and "why", not "how"
- Suitable for presentations and docs

---

## 4. Prioritization

### Phase 1: Foundation (Week 1-2)

**Goal**: Core requirements + top 10 critical algorithms documented

**Deliverables**:
```

docs/requirements/
├── SYSTEM_REQUIREMENTS.md
├── RFC-001-gateway-architecture.md
└── RFC-002-memory-backend.md

docs/algorithms/core-infrastructure/
├── 001-circuit-breaker.md
├── 002-device-pairing.md
├── 006-command-approval.md
├── 007-ssrf-protection.md

docs/algorithms/security/
├── 013-constant-time-comparison.md
├── 014-credential-encryption.md

docs/algorithms/gateway-network/
└── 018-auth-router.md

docs/algorithms/memory-search/
└── 024-memory-index.md

docs/algorithms/ui-ux/
├── 032-terminal-ui.md
└── 036-macos-appstate.md

docs/architecture/
└── OVERVIEW.md

docs/diagrams/internal/
├── gateway-auth-flow.drawio
├── device-pairing-sequence.drawio
├── circuit-breaker-states.drawio
└── security-boundaries.drawio

docs/security/
├── SECURITY_MODEL.md
└── threat-model.md

```

**Review Criteria**:
- All HIGH priority algorithms documented
- Security model complete
- Architecture overview clear
- Internal diagrams for critical flows

---

### Phase 2: Completion (Week 3-4)

**Goal**: Remaining algorithms + internal diagrams for all MEDIUM priority items

**Deliverables**:
```

docs/algorithms/
├── (all remaining 36 algorithm docs)

docs/architecture/
├── gateway-architecture.md
├── memory-architecture.md
├── security-architecture.md
├── plugin-architecture.md
└── data-flow/\*.md

docs/diagrams/internal/
├── (all 9 internal diagrams)

docs/api/
├── gateway-rpc-api.md
├── plugin-sdk-api.md
└── config-schema.md

docs/security/
├── authentication-model.md
├── credential-storage.md
├── sandbox-model.md
└── network-security.md

docs/governance/
├── GOVERNANCE_MODEL.md
├── policy-engine.md
└── rfc-process.md

```

**Review Criteria**:
- 100% algorithm coverage
- All internal diagrams complete
- API reference usable
- Security docs comprehensive

---

### Phase 3: Open Source Packaging (Week 5)

**Goal**: Public-facing documentation + repository packaging

**Deliverables**:

**Root Repository Files**:
```

README.md # Complete rewrite with architecture overview
CONTRIBUTING.md # Contribution guidelines
CODE_OF_CONDUCT.md # Contributor covenant
SECURITY.md # Enhanced with disclosure process
LICENSE # Main license (MIT/Apache 2.0)
LICENSE-THIRD-PARTY.md # Dependency licenses

```

**Public Documentation**:
```

docs/diagrams/public/
├── high-level-architecture.drawio
├── value-proposition.drawio
├── deployment-topology.drawio
├── security-boundaries.drawio
├── plugin-ecosystem.drawio
└── user-journey.drawio

docs/
├── QUICKSTART.md # 5-minute getting started
├── INSTALL.md # Platform-specific install guides
│ ├── macos.md
│ ├── linux.md
│ ├── windows.md
│ └── docker.md
├── CONFIGURATION.md # Config reference
└── EXAMPLES/
├── basic-chat.md
├── device-pairing.md
├── plugin-development.md
└── media-attachments.md

```

**Developer Onboarding**:
```

docs/developers/
├── BUILD.md # Build from source
├── TEST.md # Running tests
├── DEBUG.md # Debugging guide
├── RELEASE.md # Release process
└── ARCHITECTURE.md # Deep dive for contributors

````

**Open Source Launch Checklist**:
- [ ] README.md with compelling value proposition
- [ ] Architecture diagram in README (public version)
- [ ] Quickstart guide (get running in <5 min)
- [ ] Installation guides for all platforms
- [ ] CONTRIBUTING.md with clear contribution process
- [ ] CODE_OF_CONDUCT.md (Contributor Covenant)
- [ ] SECURITY.md with disclosure process
- [ ] LICENSE files (primary + third-party)
- [ ] Issue templates (bug, feature, security)
- [ ] Pull request template
- [ ] GitHub labels configured
- [ ] Discussion categories set up
- [ ] Code of Conduct enforcement policy
- [ ] Security committee members identified
- [ ] First 10 "good first issues" tagged
- [ ] Demo videos/screenshots in README
- [ ] Social media announcement prepared

---

## 5. Open Source Packaging Requirements

### README.md Structure

```markdown
# SophiaClaw

{One-sentence value proposition: "Open source frontier model provider with governance, memory, and multi-platform support"}

## Why SophiaClaw?

{3-5 bullet points on unique value:}
- Governed AI with policy enforcement
- Persistent memory across sessions
- Multi-platform (macOS, Linux, Windows, mobile)
- Plugin ecosystem for extensibility
- Security-first architecture

## Architecture

{Embedded public architecture diagram}

## Quickstart

{Copy-paste install + run in <5 minutes}

```bash
# Install
npm install -g sophiaclaw

# Configure
sophiaclaw config set gateway.mode local

# Run
sophiaclaw tui
````

## Features

### Governance & Policy

{Description with link to governance docs}

### Memory & Context

{Description with link to memory docs}

### Security Model

{Description with link to security docs}

### Plugin Ecosystem

{Description with link to plugin docs}

### Multi-Platform

{Platforms supported with install links}

## Documentation

| Guide                                             | Description                      |
| ------------------------------------------------- | -------------------------------- |
| [Installation](docs/INSTALL.md)                   | Platform-specific install guides |
| [Quickstart](docs/QUICKSTART.md)                  | Get started in 5 minutes         |
| [Configuration](docs/CONFIGURATION.md)            | Full config reference            |
| [Security Model](docs/security/SECURITY_MODEL.md) | Security architecture            |
| [Plugin Development](docs/plugins/DEVELOPMENT.md) | Build plugins                    |

## Community

- [Issues](link) - Report bugs or request features
- [Discussions](link) - Community discussions
- [Discord](link) - Real-time chat
- [Security](SECURITY.md) - Report vulnerabilities

## Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Good First Issues

{Dynamic widget showing tagged issues}

## License

Licensed under [MIT](LICENSE) or [Apache 2.0](LICENSE) - see LICENSE file for details.

SophiaClaw includes third-party dependencies with their own licenses. See [LICENSE-THIRD-PARTY.md](LICENSE-THIRD-PARTY.md) for details.

````

---

### CONTRIBUTING.md Structure

```markdown
# Contributing to SophiaClaw

Welcome to SophiaClaw! This document covers contribution guidelines, workflow, and standards.

## Code of Conduct

Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.

## Getting Started

### Development Setup

```bash
# Clone repository
git clone https://github.com/sophiaclaw/sophiaclaw.git
cd sophiaclaw

# Install dependencies
pnpm install

# Run tests
pnpm test

# Run in development mode
pnpm dev
````

### Documentation Setup

{If contributing docs only}

## Contribution Workflow

1. **Find an Issue**: Check [open issues](link) or [good first issues](link)
2. **Fork the Repo**: Create your own fork
3. **Create a Branch**: `git checkout -b feature/your-feature`
4. **Make Changes**: Follow coding standards below
5. **Write Tests**: Ensure 80%+ coverage
6. **Run Checks**: `pnpm check` (lint + typecheck + tests)
7. **Submit a PR**: Use PR template

## Coding Standards

### TypeScript

- Strict mode enabled
- No `any` types
- JSDoc for public APIs
- Follow existing patterns

### Testing

- Unit tests for all functions
- Integration tests for APIs
- E2E tests for critical flows
- 80%+ coverage required

### Documentation

- Update docs for user-facing changes
- Add JSDoc to new functions
- Include examples for complex logic

## Documentation Contributions

We especially welcome documentation contributions!

### Adding Algorithm Documentation

1. Copy template from `docs/algorithms/_template.md`
2. Fill in all sections
3. Add diagrams if applicable
4. Include test examples
5. Run spellcheck: `pnpm docs:check`

### Diagram Guidelines

- Use DrawIO format (.drawio + export PNG/SVG)
- Follow color scheme in `docs/diagrams/README.md`
- Keep public diagrams high-level
- Internal diagrams can be detailed

## Security Contributions

See [SECURITY.md](SECURITY.md) for vulnerability disclosure process.

## Questions?

Open an issue or ask in [Discussions](link).

````

---

### CODE_OF_CONDUCT.md

Use [Contributor Covenant 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/)

---

### SECURITY.md Enhancements

```markdown
# Security Policy

## Supported Versions

| Version | Supported |
|---------|-----------|
| Latest  | ✅ |
| Previous | ✅ |
| < Previous | ❌ |

## Reporting a Vulnerability

**DO NOT** create public issues for security vulnerabilities.

### How to Report

1. Email: security@sophiaclaw.ai (pgp encrypted preferred)
2. GitHub: Use [private vulnerability reporting](link)

### What to Include

- Description of vulnerability
- Steps to reproduce
- Impact assessment
- Suggested fix (if any)

### Response Timeline

- **Acknowledgment**: Within 48 hours
- **Assessment**: Within 7 days
- **Fix**: Depends on severity (see below)

| Severity | Fix Timeline |
|----------|--------------|
| Critical | 24-48 hours |
| High | 7 days |
| Medium | 30 days |
| Low | 90 days |

### Security Committee

Report review and response handled by:
- {Committee member 1}
- {Committee member 2}
- {Committee member 3}

## Security Model

See [docs/security/SECURITY_MODEL.md](docs/security/SECURITY_MODEL.md) for technical details.

## Acknowledgments

We thank the following for responsible disclosure:
- {List of credited researchers}
````

---

### QUICKSTART.md

````markdown
# SophiaClaw Quickstart

Get SophiaClaw running in under 5 minutes.

## Prerequisites

- Node.js 22+ ([install](link))
- npm or pnpm
- A model provider API key (OpenAI, Anthropic, etc.)

## Install

```bash
npm install -g sophiaclaw
# OR
pnpm add -g sophiaclaw
```
````

## Configure

```bash
# Set your model provider
sophiaclaw config set model.provider openai
sophiaclaw config set model.api_key $OPENAI_API_KEY

# Or use interactive setup
sophiaclaw config init
```

## Run

```bash
# Terminal UI
sophiaclaw tui

# Or run as gateway
sophiaclaw gateway run
```

## Next Steps

- [Full Installation Guide](INSTALL.md) - Platform-specific details
- [Configuration Reference](CONFIGURATION.md) - All options
- [Device Pairing](examples/device-pairing.md) - Connect mobile apps
- [Plugin Development](plugins/DEVELOPMENT.md) - Build extensions

```

---

## Appendix A: Algorithm to Document Mapping

| # | Algorithm | File Location | Priority | Target Doc Path |
|---|-----------|---------------|----------|-----------------|
| 1 | Circuit Breaker | `src/infra/circuit-breaker.ts` | HIGH | `docs/algorithms/core-infrastructure/001-circuit-breaker.md` |
| 2 | Device Pairing | `src/infra/device-pairing.ts` | HIGH | `docs/algorithms/core-infrastructure/002-device-pairing.md` |
| 3 | Log Integrity | `src/security/log-integrity.ts` | MEDIUM | `docs/algorithms/security/003-log-integrity.md` |
| 4 | DNS-SD Discovery | `src/infra/bonjour-discovery.ts` | MEDIUM | `docs/algorithms/core-infrastructure/004-dns-sd-discovery.md` |
| 5 | FS Permission Inspector | `src/security/audit-fs.ts` | MEDIUM | `docs/algorithms/security/005-fs-permission-inspector.md` |
| 6 | Command Approval | `src/infra/exec-approvals.ts` | HIGH | `docs/algorithms/core-infrastructure/006-command-approval.md` |
| 7 | SSRF Protection | `src/infra/net/ssrf.ts` | HIGH | `docs/algorithms/core-infrastructure/007-ssrf-protection.md` |
| 8 | Abort Pattern Matching | `src/infra/abort-pattern.test.ts` | LOW | `docs/algorithms/core-infrastructure/008-abort-pattern-matching.md` |
| 9 | Security Audit Engine | `src/security/audit.ts` | HIGH | `docs/algorithms/governance/009-security-audit-engine.md` |
| 10 | Dangerous Config Flags | `src/security/dangerous-config-flags.ts` | MEDIUM | `docs/algorithms/governance/010-dangerous-config-flags.md` |
| 11 | Scope Implication | `src/infra/device-pairing.ts:197-214` | MEDIUM | `docs/algorithms/governance/011-scope-implication.md` |
| 12 | Session Key Normalization | `src/routing/session-key.ts` | LOW | `docs/algorithms/governance/012-session-key-normalization.md` |
| 13 | Constant-Time Comparison | `src/security/secret-equal.ts` | HIGH | `docs/algorithms/security/013-constant-time-comparison.md` |
| 14 | Credential Encryption | `src/security/credential-encryption/` | HIGH | `docs/algorithms/security/014-credential-encryption.md` |
| 15 | Encrypted JSON Storage | `src/security/credential-encryption/encrypted-json-file.ts` | MEDIUM | `docs/algorithms/security/015-encrypted-json-storage.md` |
| 16 | Windows ACL | `src/security/windows-acl.ts` | MEDIUM | `docs/algorithms/security/016-windows-acl.md` |
| 17 | Audit Log Aggregator | `src/security/audit-*.ts` | MEDIUM | `docs/algorithms/security/017-audit-log-aggregator.md` |
| 18 | Gateway Auth Router | `src/gateway/auth.ts` | HIGH | `docs/algorithms/gateway-network/018-auth-router.md` |
| 19 | Auth Rate Limiter | `src/gateway/auth-rate-limit.ts` | MEDIUM | `docs/algorithms/gateway-network/019-rate-limiter.md` |
| 20 | Client IP Resolution | `src/gateway/net.ts` | MEDIUM | `docs/algorithms/gateway-network/020-client-ip-resolution.md` |
| 21 | Connection Manager | `src/gateway/call.ts` | MEDIUM | `docs/algorithms/gateway-network/021-connection-manager.md` |
| 22 | Node Registry | `src/gateway/node-registry.ts` | MEDIUM | `docs/algorithms/gateway-network/022-node-registry.md` |
| 23 | Fallback Memory Manager | `src/memory/search-manager.ts` | MEDIUM | `docs/algorithms/memory-search/023-fallback-manager.md` |
| 24 | Memory Index | `src/memory/manager.ts` | HIGH | `docs/algorithms/memory-search/024-memory-index.md` |
| 25 | QMD Backend | `src/memory/qmd-manager.ts` | MEDIUM | `docs/algorithms/memory-search/025-qmd-backend.md` |
| 26 | Backend Config Resolver | `src/memory/backend-config.ts` | LOW | `docs/algorithms/memory-search/026-backend-config.md` |
| 27 | Agent Scope Resolver | `src/agents/agent-scope.ts` | MEDIUM | `docs/algorithms/agent-management/027-agent-scope.md` |
| 28 | API Key Rotation | `src/agents/api-key-rotation.ts` | MEDIUM | `docs/algorithms/agent-management/028-api-key-rotation.md` |
| 29 | Auth Cooldown | `src/agents/auth-profiles.ts` | LOW | `docs/algorithms/agent-management/029-auth-cooldown.md` |
| 30 | Bash Registry | `src/agents/bash-process-registry.ts` | LOW | `docs/algorithms/agent-management/030-bash-registry.md` |
| 31 | Apply Patch Engine | `src/agents/apply-patch.ts` | MEDIUM | `docs/algorithms/agent-management/031-apply-patch.md` |
| 32 | Terminal UI | `src/tui/tui.ts` | HIGH | `docs/algorithms/ui-ux/032-terminal-ui.md` |
| 33 | Burst Coalescer | `src/tui/tui.ts:82-180` | LOW | `docs/algorithms/ui-ux/033-burst-coalescer.md` |
| 34 | OSC8 Hyperlinks | `src/tui/osc8-hyperlinks.ts` | LOW | `docs/algorithms/ui-ux/034-osc8-hyperlinks.md` |
| 35 | Gateway Chat | `src/tui/gateway-chat.ts` | LOW | `docs/algorithms/ui-ux/035-gateway-chat.md` |
| 36 | macOS AppState | `apps/macos/Sources/SOPHIAClaw/Core/AppState.swift` | HIGH | `docs/algorithms/platforms/036-macos-appstate.md` |
| 37 | macOS Permissions | `apps/macos/Sources/SOPHIAClaw/Core/PermissionManager.swift` | MEDIUM | `docs/algorithms/platforms/037-macos-permissions.md` |
| 38 | macOS WebSocket | `apps/macos/Sources/SOPHIAClaw/Services/` | MEDIUM | `docs/algorithms/platforms/038-macos-websocket.md` |
| 39 | Plugin HTTP Auth | `src/gateway/server.plugin-http-auth.test.ts` | MEDIUM | `docs/algorithms/plugins/039-plugin-http-auth.md` |
| 40 | Channel Registry | `src/channels/plugins/index.ts` | MEDIUM | `docs/algorithms/plugins/040-channel-registry.md` |
| 41 | Plugin SDK | `src/plugin-sdk/` | MEDIUM | `docs/algorithms/plugins/041-plugin-sdk.md` |
| 42 | Extension Entrypoint | `extensions/*/index.ts` | LOW | `docs/algorithms/plugins/042-extension-entrypoint.md` |
| 43 | Media Understanding | `src/media-understanding/` | HIGH | `docs/algorithms/media/043-media-understanding.md` |
| 44 | Attachment Normalizer | `src/gateway/server-methods/attachment-normalize.ts` | LOW | `docs/algorithms/media/044-attachment-normalizer.md` |
| 45 | Credential Storage | `src/security/credential-encryption/` | HIGH | `docs/algorithms/security/014-credential-encryption.md` |
| 46 | Platform Detection | `src/infra/platform.ts` | LOW | (utility - no dedicated doc) |
| 47 | Homebrew Integration | `src/infra/brew.ts` | LOW | (utility - no dedicated doc) |
| 48 | System Presence | `src/infra/system-presence.ts` | LOW | (utility - no dedicated doc) |

---

## Appendix B: Diagram Checklist

### Internal Diagrams (9 total)

- [ ] gateway-auth-flow.drawio - Gateway authentication state machine
- [ ] device-pairing-sequence.drawio - Device pairing sequence diagram
- [ ] circuit-breaker-states.drawio - Circuit breaker state transitions
- [ ] memory-backend-failover.drawio - Memory backend failover logic
- [ ] plugin-isolation-model.drawio - Plugin sandbox architecture
- [ ] security-audit-checks.drawio - Audit engine check flow
- [ ] gateway-auth-router.drawio - Auth method routing logic
- [ ] media-pipeline-stages.drawio - Media processing pipeline
- [ ] agent-scope-resolution.drawio - Multi-tenant scope resolution

### Public Diagrams (6 total)

- [ ] high-level-architecture.drawio - System overview diagram
- [ ] value-proposition.drawio - User value flow
- [ ] deployment-topology.drawio - Deployment scenarios
- [ ] security-boundaries.drawio - Trust boundaries diagram
- [ ] plugin-ecosystem.drawio - Plugin integration model
- [ ] user-journey.drawio - End-user experience flow

---

*Generated: 2026-03-11 | SophiaClaw Open Source Documentation Initiative*
```