ADR-018: PET App Technical Architecture

spec_id: ADR-018 title: PET App Technical Architecture bounded_context: shared status: Accepted version: 1.1.0 date_created: 2025-12-21 last_updated: 2026-01-03 supersedes: null related_adrs: [] related_prds:

PRD-004

Context

The Prompt Engineer Training (PET) app requires a robust, scalable architecture to support:

Dual Audiences: Individual learners (consumer) and Enterprise teams (on-prem, custom rules).
Multiple Clients: Web, Desktop (Tauri), and potential Mobile.
Maintainability: Low technical debt while supporting complex domain logic (Judging, Learning Paths).
Global Reach: Mandatory multilingual support.
Enterprise Integration: SCORM/xAPI support, local data sovereignty.

Decision

We will adopt the following architectural strategies:

1. Nx Modular Monolith with Hexagonal Architecture

We will build a single monorepo using Nx to manage boundaries.

Backend: NestJS (Modular Monolith).
Frontend: Next.js (Web) + React (Desktop/Mobile shared libs).
Desktop: Tauri (wrapping the React frontend).
Shared Libraries: Core domain logic will be in framework-independent TypeScript libraries (libs/domain-*), following DDD/Hexagonal Architecture principles (Ports & Adapters).

Project Structure:

apps/web: Next.js client.
apps/desktop: Tauri shell.
apps/api: NestJS backend.
libs/domain-*: Pure business logic (Entities, Value Objects, Use Cases).
libs/infrastructure-*: Adapters (DB, LLM, Auth).
libs/contracts: Shared DTOs/Schemas.

2. Multi-Lingual by Default

The system must support native-language prompts out of the box.

Judge Logic: Detects input language -> Generates feedback in that language.
UI: Fully localized.
Lessons: v1 templates in English, but architecture supports localized content.

3. Modular “Pipeline” Judge

(Unchanged from initial concept)

Single LLM call with strict JSON schema enforcing “Sub-Judges” (Intent, Structure, Agentic, Safety).
Enterprise “Best Practices” are injected as context/rules into this pipeline.

4. Hybrid Lesson Content (Template + Context)

(Refined)

No purely generative lessons.
Lessons use human-authored templates populated with user-specific examples (via LLM).
Enterprise Publishing: Enterprises can publish completely custom “Best Practice” documents that integrate into the Lesson engine.

5. Enterprise Interoperability via Standards

No direct integrations (Slack, GitHub) in v1.
LMS Integration: Exclusively via SCORM/xAPI exports.
Deployment: Supports containerized on-premise deployment with field-level encryption for prompts.

Rationale

Nx Monolith: Maximizes code sharing (contracts, types, domain logic) between Web/Desktop/API without the complexity of microservices.
Hexagonal: Decouples core “Training” logic from infrastructure (Database, specific LLM provider), allowing easy swapping of LLMs or DBs for on-prem enterprise.
Tauri: Provides a native desktop experience with lower resource usage than Electron, fitting the “Pro Tool” vibe.
Multilingual: Critical for global enterprise adoption where prompts are often in local languages.

Constraints

MUST use Nx modular monorepo with strict boundary enforcement
MUST use hexagonal architecture (Ports & Adapters) for domain logic
MUST support multilingual prompts and UI from v1
MUST use SCORM/xAPI for LMS integration
MUST support containerized on-premise deployment
MUST NOT use purely generative lessons without human-authored templates

Quality Attributes

High code reuse across platforms
Strict boundaries preventing architectural decay
Multi-platform readiness (Web, Desktop, Mobile)
Enterprise-grade security with field-level encryption
Global reach via multilingual support

Bounded Contexts Impacted

Training Domain (Judging, Learning Paths)
User Management
Enterprise Configuration
Content Publishing

Consequences

Positive

High code reuse
Strict boundaries prevent “spaghetti code”
Ready for multiple platforms
Enterprise-compatible from day one

Negative

Higher initial setup complexity (Nx, DDD boilerplate) compared to a simple MVC app