Architecture

Architecture Documentation

This document describes the technical architecture of Thought Ledger, including system components, data flow, and design decisions.

System Overview

Thought Ledger is a local-first AI decision memory system that runs entirely on your device. The architecture prioritizes privacy, performance, and user control.

Core Principles

Local Processing: All AI processing happens locally
Privacy by Design: No data leaves the device
Modular Architecture: Components can be updated independently
Open Standards: Uses open formats and protocols

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Thought Ledger System                      │
├─────────────────────────────────────────────────────────────┤
│  Web Interface (React/Astro)                                │
│  ├── Decision Dashboard                                     │
│  ├── AI Chat Interface                                      │
│  └── Analytics & Patterns                                   │
├─────────────────────────────────────────────────────────────┤
│  API Layer (Node.js/Express)                                │
│  ├── Decision Management                                    │
│  ├── AI Integration                                         │
│  └── Search & Retrieval                                      │
├─────────────────────────────────────────────────────────────┤
│  Core Services                                               │
│  ├── Decision Memory Engine                                  │
│  ├── Pattern Analysis                                        │
│  └── Context Management                                      │
├─────────────────────────────────────────────────────────────┤
│  AI Layer                                                    │
│  ├── Ollama Integration                                      │
│  ├── Model Management                                        │
│  └── Prompt Engineering                                      │
├─────────────────────────────────────────────────────────────┤
│  Data Layer                                                  │
│  ├── SQLite Database                                        │
│  ├── Vector Storage (Embeddings)                            │
│  └── File System (Exports/Backups)                          │
└─────────────────────────────────────────────────────────────┘

Component Architecture

1. Web Interface

Technology Stack: Astro, React, Tailwind CSS

Responsibilities:

User interaction and decision entry
Real-time AI chat interface
Data visualization and analytics
Responsive design for all devices

Key Features:

Server-Side Rendering (SSR) for performance
Progressive Web App (PWA) capabilities
Offline functionality
Component-based architecture

2. API Layer

Technology Stack: Node.js, Express.js, TypeScript

Endpoints:

// Decision Management
POST   /api/decisions              // Create new decision
GET    /api/decisions              // List decisions
GET    /api/decisions/:id          // Get specific decision
PUT    /api/decisions/:id          // Update decision
DELETE /api/decisions/:id          // Delete decision

// AI Integration
POST   /api/ai/assist              // Get AI assistance
POST   /api/ai/chat                // AI chat interface
GET    /api/ai/models              // Available AI models

// Search & Analytics
GET    /api/search                 // Search decisions
GET    /api/analytics/patterns     // Decision patterns
GET    /api/analytics/insights     // Personal insights

3. Core Services

Decision Memory Engine

class DecisionMemoryEngine {
  // Store decisions with full context
  async storeDecision(decision: Decision): Promise<void>

  // Retrieve relevant decisions for context
  async getRelevantDecisions(context: string): Promise<Decision[]>

  // Update decision with outcomes
  async updateDecisionOutcome(id: string, outcome: Outcome): Promise<void>

  // Analyze decision patterns
  async analyzePatterns(userId: string): Promise<Pattern[]>
}

Pattern Analysis Service

class PatternAnalysisService {
  // Identify recurring decision types
  async identifyDecisionPatterns(decisions: Decision[]): Promise<Pattern[]>

  // Analyze success factors
  async analyzeSuccessFactors(decisions: Decision[]): Promise<Factor[]>

  // Detect personal biases
  async detectBiases(decisions: Decision[]): Promise<Bias[]>

  // Generate insights
  async generateInsights(userId: string): Promise<Insight[]>
}

4. AI Layer

Ollama Integration

class OllamaService {
  private baseUrl: string = "http://localhost:11434"

  // Generate AI response
  async generate(prompt: string, model: string): Promise<string>

  // List available models
  async listModels(): Promise<Model[]>

  // Pull new model
  async pullModel(model: string): Promise<void>

  // Check model health
  async healthCheck(): Promise<boolean>
}

Prompt Engineering

Thought Ledger uses specialized prompts for different tasks:

Decision Assistance Prompt:

You are a decision assistant with access to the user's past decisions.
Context: {current_context}
Relevant History: {relevant_decisions}
User's Decision Patterns: {user_patterns}

Provide insights for this decision considering:
1. Similar past decisions and their outcomes
2. The user's typical decision patterns
3. Potential blind spots or biases
4. Risk factors based on history

Pattern Analysis Prompt:

Analyze these decisions for patterns:
{decision_history}

Identify:
1. Reccurring decision types
2. Success/failure patterns
3. Decision-making tendencies
4. Areas of strength and improvement

5. Data Layer

Database Schema

-- Decisions table
CREATE TABLE decisions (
  id TEXT PRIMARY KEY,
  title TEXT NOT NULL,
  context TEXT,
  options TEXT, -- JSON array
  selected_option TEXT,
  reasoning TEXT,
  confidence_level INTEGER,
  created_at DATETIME,
  updated_at DATETIME,
  tags TEXT, -- JSON array
  metadata TEXT -- JSON object
);

-- Outcomes table
CREATE TABLE outcomes (
  id TEXT PRIMARY KEY,
  decision_id TEXT,
  outcome_description TEXT,
  success_rating INTEGER,
  lessons_learned TEXT,
  recorded_at DATETIME,
  FOREIGN KEY (decision_id) REFERENCES decisions(id)
);

-- Embeddings for semantic search
CREATE TABLE decision_embeddings (
  decision_id TEXT,
  embedding BLOB, -- Vector representation
  model_name TEXT,
  created_at DATETIME,
  FOREIGN KEY (decision_id) REFERENCES decisions(id)
);

Vector Storage

For semantic search and similarity matching:

Embedding Models: Use local sentence transformers
Vector Database: SQLite with vector extensions
Similarity Search: Cosine similarity for decision matching

Data Flow

Decision Creation Flow

User Input → Web Interface → API Layer → Validation
    ↓
Decision Memory Engine → Database Storage → Vector Embedding
    ↓
AI Service → Context Analysis → Pattern Update → User Response

AI Assistance Flow

User Query → Web Interface → API Layer → Context Retrieval
    ↓
Relevant Decisions → Pattern Analysis → AI Service (Ollama)
    ↓
AI Response → Insight Generation → Web Interface → User

Pattern Analysis Flow

Scheduled Task → Decision Retrieval → Pattern Analysis Service
    ↓
Machine Learning → Pattern Detection → Insight Generation
    ↓
Database Update → Notification Service → User Interface

Security Architecture

Privacy Protection

Local Processing: All data processing on-device
No Network Calls: No external API calls for core functionality
Encryption: Sensitive data encrypted at rest
Access Control: Optional authentication for sensitive decisions

Data Security

class SecurityService {
  // Encrypt sensitive decision data
  async encryptDecision(data: string, key: string): Promise<string>

  // Validate user access
  async validateAccess(userId: string, decisionId: string): Promise<boolean>

  // Audit logging for security events
  async logSecurityEvent(event: SecurityEvent): Promise<void>
}

Performance Optimization

Caching Strategy

Decision Cache: Frequently accessed decisions in memory
AI Response Cache: Cache AI responses for similar queries
Pattern Cache: Pre-computed patterns for faster analysis

Database Optimization

Indexing: Strategic indexes on common query patterns
Connection Pooling: Efficient database connections
Batch Operations: Bulk operations for large datasets

AI Performance

Model Selection: Choose appropriate model size for hardware
Prompt Caching: Cache prompt templates and responses
Parallel Processing: Multiple AI requests when possible

Deployment Architecture

Local Deployment

User Device
├── Thought Ledger Application
├── Ollama Service
├── SQLite Database
└── Configuration Files

Development Environment

# docker-compose.yml for development
version: "3.8"
services:
  thought-ledger:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
    environment:
      - NODE_ENV=development

  ollama:
    image: ollama/ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama

volumes:
  ollama_data:

Extensibility

Plugin Architecture

interface Plugin {
  name: string
  version: string
  initialize(context: PluginContext): Promise<void>
  onDecisionCreate(decision: Decision): Promise<void>
  onAIResponse(response: AIResponse): Promise<void>
}

Integration Points

Webhook Support: External system notifications
API Extensions: Custom endpoints for specific needs
Model Plugins: Support for different AI models
Export Plugins: Custom export formats

Monitoring & Observability

Health Checks

class HealthService {
  async checkDatabase(): Promise<HealthStatus>
  async checkAIService(): Promise<HealthStatus>
  async checkSystemResources(): Promise<HealthStatus>
  async generateHealthReport(): Promise<HealthReport>
}

Metrics Collection

Decision Metrics: Volume, types, outcomes
AI Performance: Response times, model usage
System Performance: Memory, CPU, storage usage
User Engagement: Feature usage, session duration

This architecture ensures Thought Ledger remains private, performant, and user-controlled while providing powerful AI-assisted decision memory capabilities.