1. High-Level Design

TextFoundry в текущей кодовой базе - это desktop workbench для authoring, versioning и deterministic rendering prompt assets, с optional AI-assisted workflow поверх того же core engine.

При этом целевая архитектурная траектория уже шире:

  • workbench для authoring;

  • core engine для deterministic assembly;

  • future prompt server для published prompt registry and render delivery;

  • dual-language runtime surfaces для C++ и Python.

1. System Summary

Система разделена на пять крупных слоев:

  • textfoundry_engine - core domain model, versioning, rendering, validation

  • ObjectBox repositories - локальное persistent storage для blocks и compositions

  • textfoundry_ai - OpenAI-compatible adapters и HTTP transport

  • text_foundry_gui - Qt/QML desktop authoring UI

  • text_foundry_cli - FTXUI terminal frontend

Целевой следующий слой, пока не реализованный:

  • prompt_server - published-only registry/render runtime для downstream clients

  • language_surfaces - C++ and Python local/remote APIs over shared semantics

2. Architectural Boundary

Главная архитектурная граница проекта:

  • deterministic authoring/rendering path живет в core engine

  • AI-функции подключаются как optional adapters через интерфейсы engine

  • UI инициирует AI-вызовы только явно, а не внутри обычного render path

Это значит:

  • render остается воспроизводимым без LLM

  • при отсутствии AI configuration базовые block/composition workflows работают

  • AI влияет только на explicit authoring/rewrite actions

3. Core Runtime Flow

Diagram

4. Domain Model

Основные сущности:

  • Block - versioned reusable template with defaults, tags, language and type

  • Composition - ordered list of fragments

  • Fragment - BlockRef, StaticText или Separator

  • RenderContext - runtime parameter overrides и strict-mode policy

  • StyleProfile - structural style и semantic style

Versioning встроен в core:

  • blocks и compositions публикуются как immutable versions

  • update workflows создают новый version, а не перезаписывают старый

  • deprecate/delete выполняются отдельными explicit actions

5. Implemented Capability Set

Реально поддерживаемые capability на April 16, 2026:

  • block generation

  • prompt slicing

  • normalization

  • composition rewrite

  • deterministic render and preview

  • local authoring and storage

Не реализовано, но описано в документации как future boundary:

  • prompt server as published prompt registry and deterministic render API

6. Storage and Session Model

Storage слой реализован через ObjectBox:

  • blocks и их версии хранятся как persistent entities

  • compositions и fragments хранятся отдельно

  • GUI session использует projectKey и dataPath для rebuild engine

Практическое следствие:

  • приложение ориентировано на local-first desktop usage

  • AI provider не имеет прямого доступа к storage

  • persistence mutation остается на стороне engine после review/apply

В future server model:

  • published assets будут доступны через server boundary;

  • backend, C++ и Python clients смогут получать render без desktop workflow;

  • draft/published separation должна сохраниться и на сервере.

Language model в целевой архитектуре:

  • C++ и Python должны быть first-class surfaces;

  • local APIs работают поверх engine;

  • remote APIs работают поверх prompt server;

  • parity должна удерживаться на уровне semantics, а не на уровне буквального синтаксиса.

7. AI Integration Model

textfoundry_ai содержит provider-specific реализации:

  • OpenAiCompatibleBlockGenerator

  • OpenAiCompatibleNormalizer

  • OpenAiCompatibleCompositionBlockRewriter

  • QtHttpTransport

Engine contracts, через которые они подключаются:

  • IBlockGenerator

  • INormalizer

  • IBlockNormalizer

  • ICompositionBlockRewriter

Все AI вызовы зависят от настроек base_url, model, api_key и timeout, получаемых из GUI session settings.

8. Reliability Model

Базовая стратегия деградации:

  • если AI adapter не настроен, deterministic core остается доступен

  • если provider вернул ошибку, UI остается в ручном workflow

  • auto-publish и hidden mutation отсутствуют

9. Downstream Docs

Следующими источниками детализации для этого HLD являются:

Диаграммы в этом разделе должны оформляться в mermaid.