Architecture Overview

Folionaut follows a layered architecture with clear separation of concerns. This section covers the system design at various levels of detail.

Documentation Structure

Document	Description
High-Level Design	System context, containers, deployment
Low-Level Design	Components, classes, sequences
Content Model	Data schemas and validation

Design Principles

1. Clean Architecture

The codebase follows clean architecture principles:

• Routes - HTTP handling, request/response transformation
• Services - Business logic, orchestration
• Repositories - Data access abstraction
• Infrastructure - Cross-cutting concerns (cache, events, metrics)

2. Dependency Injection

All dependencies are injected, enabling:

• Easy unit testing with mocks
• Flexible configuration
• Clear dependency graphs

3. Event-Driven Side Effects

Side effects (cache invalidation, metrics, audit logs) are decoupled via events:

This keeps core logic focused and testable.

System Overview

Key Components

Content Management

• Single content table with flexible JSON data column
• Type-specific validation via Zod schemas
• Version history tracking with restore capability
• Soft deletes for safety

Chat System

• Session-based conversations
• Input/output guardrails with PII sanitization
• Token bucket rate limiting
• Circuit breaker for resilience

MCP Server

• Dual transport: stdio (local) and Streamable HTTP (remote via /api/mcp)
• Tools for CRUD operations
• Resources for reading content
• Prompts for common use cases
• Shared data layer with REST API

Architecture Decision Records

Key decisions are documented as ADRs:

ADR	Decision
001	Turso (libSQL) for database
002	Layered caching with Redis
003	Provider abstraction layer
004	Repository pattern for data access
005	Events and OpenTelemetry tracing
006	Guardrails-based PII protection
007	Flexible content model
008	Shared tools architecture