Veritheia Documentation

An environment for inquiry - complete documentation

View the Project on GitHub ZipThought/veritheia

Veritheia Implementation

1. Overview

This document specifies the technical implementation of Veritheia. The system operates as a local-first epistemic infrastructure with four primary components: PostgreSQL with pgvector for knowledge storage, ASP.NET Core for process orchestration, adapter-based LLM integration for assessments, and Blazor Server for user interfaces. All components enforce user data sovereignty and prevent automated insight generation.

2. Technology Stack

2.1 Knowledge Database

PostgreSQL 16 with pgvector extension provides unified storage for documents, metadata, and embeddings. The pgvector extension enables efficient similarity search over 1536-dimensional embedding vectors while maintaining ACID guarantees for relational data. Deployment uses containerization through .NET Aspire for consistent development and production environments.

2.2 Process Engine

ASP.NET Core 8.0 implements the Process Engine as a RESTful API service. The architecture employs Domain-Driven Design with aggregate boundaries around User, Journey, and Document entities. Data access uses the Repository pattern with Entity Framework Core 8.0, while CQRS separates read and write operations for scalability.

2.3 Presentation Tier

Blazor Server provides the web interface, enabling real-time updates through SignalR connections. This architecture choice eliminates JavaScript complexity while maintaining responsive user experiences. Component design follows a strict separation between user-authored content display and system-provided structure.

2.4 Cognitive System Integration

The ICognitiveAdapter interface abstracts LLM implementation details, supporting multiple backends: LlamaCppAdapter for local inference, SemanticKernelAdapter for Microsoft Semantic Kernel, and OpenAIAdapter for cloud-based models. Each adapter implements assessment-only operations, preventing insight generation through prompt engineering constraints.

Data Architecture

Entity Model

The data layer (veritheia.Data) defines these core entities:

Primary Key Strategy

All entities use ULID (Universally Unique Lexicographically Sortable Identifier) as primary keys:

Database Design Patterns

Vector Storage Strategy

Database Migrations

The system uses Entity Framework Core migrations with this workflow:

  1. Define entity changes in veritheia.Data
  2. Generate migrations from veritheia.ApiService context
  3. Apply migrations during startup or deployment

Service Architecture

Dependency Injection Structure

The application uses ASP.NET Core’s built-in dependency injection with these service lifetimes:

Platform Services

The platform provides guaranteed services that all processes can depend on:

Process Registration

Processes are registered through a convention-based pattern that ensures proper dependency injection and discovery. Each process is registered both as itself and as an IAnalyticalProcess implementation.

Process Architecture

Process Execution Flow

  1. Input Collection: Dynamic forms generated from process definition
  2. Context Creation: User journey and inputs packaged into ProcessContext
  3. Process Execution: Business logic runs with access to platform services
  4. Result Storage: Outputs saved with full provenance and versioning
  5. Result Rendering: Process-specific UI components display results

Reference Process Patterns

Systematic Screening Process (Analytical Pattern)

Journal Integration:

Guided Composition Process (Compositional Pattern)

Journal Integration:

Process Context

Every process execution receives a context that includes:

Context Assembly:

  1. Journal Selection: Relevant journals for current task
  2. Entry Extraction: Recent significant entries
  3. Narrative Compression: Maintaining coherence within token limits
  4. Persona Integration: User’s conceptual vocabulary and patterns

This context ensures outputs remain personally relevant and meaningful within the specific inquiry.

Extension Architecture

Extension Points

The system provides several extension points for adding new capabilities:

  1. Process Extensions: New analytical workflows via IAnalyticalProcess
  2. Data Model Extensions: Domain-specific entities related to process executions
  3. UI Component Extensions: Custom Blazor components for process interfaces
  4. Result Renderer Extensions: Specialized visualization for process outputs

Extension Integration

Extensions integrate through:

For detailed extension development, see EXTENSION-GUIDE.md.

Development Environment

Local Development Setup

  1. Prerequisites: .NET 8 SDK, Docker Desktop, PostgreSQL client tools
  2. Configuration: Local settings in appsettings.Development.json
  3. Startup: Run via .NET Aspire for orchestrated services
  4. Access Points:
    • Web UI: https://localhost:5001
    • API: https://localhost:5000
    • Aspire Dashboard: https://localhost:15000

Testing Approach

Debugging Tools

Security Patterns

Authentication & Authorization

Data Protection

Performance Optimization

Caching Strategy

Scaling Patterns

Deployment Considerations

Container Strategy

Configuration Management

Monitoring & Observability

API Design Principles

RESTful Conventions

Response Patterns

All API responses follow a consistent structure with success indicators, data payloads, and error information. Pagination is implemented for list endpoints.

Versioning Strategy

Design Patterns

All implementations MUST follow the imperative patterns documented in DESIGN-PATTERNS.md.

Key patterns include:

See DESIGN-PATTERNS.md for complete implementation details and code examples.