Architecture Overview

Architecture Overview

Tepegoz is a layered modular monolith: one Electron desktop app over many private @tepegoz/* packages. The desktop app should stay thin; reusable or domain-specific work belongs in packages.

Layer Model

Layer	Responsibility
L0 Core Shell	Electron windowing, sandboxing, typed IPC
L1 Persistence	SQLite, event journal, blob store
L2 Durability and Memory	Checkpoint/resume, handoff, task memory
L3 Orchestrator	Intent to plan, scheduling, loop detection
L4 Perception and Tools	CDP driver, DOM/accessibility perception, content sanitizer
L5 Capability Plane	Tool gateway, policy enforcement point, skills, MCP client
L6 Integration Adapters	Official-API-first connectors and browser fallback
L7 Model Gateway	Provider routing, transports, token ledger
L8 Security Kernel	Policy kernel, egress firewall, HITL, capability broker
L9 Browser UI	Command palette, console, chrome, settings
L10 Safe Browsing	Adblock, popup/permission guard, threat shield

Some layers describe the target architecture more than fully closed implementation. The source docs state which pieces are shipped, inert, partial, or deferred.

Process Model

The desktop app uses:

• privileged main process,
• typed preload bridge,
• untrusted renderer,
• isolated web content,
• subprocesses or helper processes where needed.

The renderer displays and relays. It does not enforce autonomy, grant permissions, or store secrets.

Boundaries

• Zod safeParse at trust boundaries.
• Typed IPC contracts.
• @tepegoz/shared-types as schema source.
• dependency-cruiser layer rules and no import cycles.
• Uniform AppError mapping at boundaries.

Package Strategy

Packages are private workspace packages and bundled into the app. They are not intended to be published to npm. New work should target the owning package or a new package, not uncontrolled growth inside apps/desktop.

Sources

• docs/architecture.md
• docs/package-map.md
• apps/desktop/README.md
• docs/adr/
• dependency-cruiser.cjs