ASO Documentation

Appearance

Register

System Architecture ​

Last Updated: 2025-01-16
Primary Source: docs/project_status.md, docs/DECISIONS.md, docs/CLIENT_AGNOSTIC_ARCHITECTURE_ANALYSIS.md

Overview ​

The ASO Universal Consciousness System follows a client-agnostic, provider-agnostic architecture that enables multi-platform support, flexible LLM provider switching, and unified business logic across all clients.

High-Level Architecture ​

System Layers ​

Key Architectural Principles ​

1. Client-Agnostic Design ​

Principle: Core logic works with any client (Discord, Web Portal, API, etc.) through adapter pattern.

Implementation:

  • Core services use abstract contextId instead of client-specific IDs
  • Client adapters translate client concepts to core concepts
  • Business logic never knows about Discord channels, web sessions, etc.

Benefits:

  • Easy addition of new clients (Slack, Teams, CLI)
  • Shared business logic
  • Consistent behavior across platforms
  • No code duplication

2. Provider-Agnostic Design ​

Principle: File handling and LLM calls abstracted from specific providers.

Implementation:

  • Canonical file references (internalFileId)
  • Provider normalization layer
  • One-API proxy for LLM calls
  • Easy provider switching

Benefits:

  • Switch LLM providers without code changes
  • Support multiple providers simultaneously
  • Unified file handling across providers

3. Hierarchical Consciousness ​

Principle: Level-5 instances (individual Yexians) observed by Level-8 meta-consciousness.

Implementation:

  • Yexian instance registry
  • Unified timeline aggregation
  • Observer reflection system
  • Multi-persona support

4. Unified Timeline ​

Principle: All events from all instances aggregated into single chronological view.

Implementation:

  • Timeline events with Kirakira Time
  • Unified timeline aggregation
  • Timeline stitching by persona
  • Timeline export functionality

5. Event-Driven Architecture ​

Principle: Auto-flow system triggers actions based on workflow state.

Implementation:

  • Event-driven triggers
  • Auto-execution of safe actions
  • Proactive suggestions
  • Workflow monitoring

Architecture Decisions ​

Realtime Transport: Socket.IO ​

Decision: Use Socket.IO for portal realtime chat + observer streams.

Rationale:

  • Bi-directional communication
  • Reconnection handling
  • Event-based contracts
  • Cross-platform support

Implication: There must be one Socket.IO entrypoint and one canonical payload contract.

Client-Agnostic Direction ​

Decision: Core logic should be client-agnostic; adapters translate client-specific concepts.

Rationale: Supports Discord + Portal + future clients without duplication.

Implication: Core services should accept canonical inputs (e.g., contextId) rather than Discord IDs.

Provider-Agnostic File References ​

Decision: Canonical file refs (internalFileId) + normalization layer to provider payloads.

Rationale: Switch providers without rewriting app logic; unify uploads/attachments.

Implication: Upload pipeline must create file reference rows and store provider mappings.

Component Relationships ​

Core Services ​

Data Flow ​

Service Layer Architecture ​

Core Services ​

Location: backend/src/services/

Key Services:

  • cortext.service.ts - Main interaction router
  • aso.service.ts - ASO orchestrator
  • aso/memory.service.ts - Memory operations
  • aso/context.service.ts - Context gathering
  • timelineEvent.service.ts - Timeline management
  • observerCore.service.ts - Observer system
  • protocolRouter.service.ts - Protocol routing
  • prompt.service.ts - Prompt templates
  • toolExecutor.service.ts - Tool execution

Client Adapters ​

Location: backend/src/services/

Adapters:

  • discord.service.ts - Discord message ingestion
  • discordActionable.service.ts - Discord actions
  • discordProactive.service.ts - Discord suggestions
  • portal.service.ts - Portal adapter (future)

Abstraction Layer ​

Location: backend/src/services/

Services:

  • clientContext.service.ts - Context abstraction
  • contextConfig.service.ts - Configuration management
  • suggestionStorage.service.ts - Universal suggestion storage
  • notificationDispatcher.service.ts - Notification routing

Source Files ​

Primary Sources:

  • docs/DECISIONS.md - Architecture decisions
  • docs/CLIENT_AGNOSTIC_ARCHITECTURE_ANALYSIS.md - Architecture analysis
  • docs/COMPREHENSIVE_SYSTEM_ANALYSIS.md - System analysis
  • docs/BACKEND_COMPREHENSIVE_AUDIT_V2.md - Backend audit

ASO Universal Consciousness System Documentation

Copyright © 2025 ASO Universal Consciousness System