Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
207 lines (168 loc) · 9.62 KB

ARCHITECTURE.md

File metadata and controls

207 lines (168 loc) · 9.62 KB

Architecture

Package structure, dependency graph, and build order for Agentage Desktop.

Monorepo Layout

agentage-desktop/
├── packages/
│   ├── shared/            Zod schemas, types, transport layer
│   ├── agent-core/        Agent base types and interfaces
│   ├── agent-from-md/     Markdown-to-agent parser (SKILL.md)
│   ├── agent-runtime/     Agent execution runtime
│   ├── agent-registry/    Multi-source agent discovery
│   ├── agent-manager/     Agent lifecycle management
│   ├── core/              Business logic, Claude/Copilot SDK integration
│   ├── frontend/          React SPA (renderer process)
│   ├── server/            Express API server (web mode)
│   └── electron/          Electron main + preload (desktop mode)
├── tests/                 Playwright E2E + test infrastructure
├── requirements/          Living requirement specs
├── docs/                  Technical documentation
├── scripts/               Build, release, and test automation
├── proof-assets/          Before/after evidence for PRs
└── .github/               Workflows and prompt files

Package Dependency Graph

                    shared          agent-core
                   /  |  \          /    |    \
                  /   |   \        /     |     \
                 /    |    \      /      |      \
              core frontend  \  agent-  agent-  agent-
               |         electron from-md runtime registry
               |                           \       /
               |                         agent-manager
               |                              |
               ├──────────────────────────────┤
               |                              |
             server                       electron

Internal dependencies (which package imports which)

Package Depends on
@agentage/shared --
@agentage/agent-core --
@agentage/agent-from-md agent-core
@agentage/agent-runtime agent-core
@agentage/agent-registry agent-core, agent-from-md
@agentage/agent-manager agent-core, agent-runtime, agent-registry
@agentage/core shared, agent-manager, agent-registry, agent-runtime
@agentage/frontend shared
@agentage/server shared, core, agent-manager, agent-registry, agent-runtime
@agentage/electron shared, core, agent-manager, agent-registry, agent-runtime

Build Order

The root npm run build script builds packages sequentially respecting dependencies:

Stage 1:  shared, agent-core                (no internal deps)
Stage 2:  agent-from-md, agent-runtime      (depend on agent-core)
Stage 3:  agent-registry                    (depends on agent-core + agent-from-md)
Stage 4:  agent-manager                     (depends on core + runtime + registry)
Stage 5:  core, frontend                    (core depends on shared + agent-*)
Stage 6:  server, electron                  (depend on everything above)

When you modify a package, rebuild it and everything downstream:

# Changed shared? Rebuild shared + everything that imports it
npm run build -w @agentage/shared
npm run build -w @agentage/core
# ... then server/electron/frontend as needed

# Changed agent-core? Rebuild the agent chain
npm run build -w @agentage/agent-core
npm run build -w @agentage/agent-from-md
npm run build -w @agentage/agent-runtime
npm run build -w @agentage/agent-registry
npm run build -w @agentage/agent-manager

Build Systems

Package Compiler Bundler Notes
shared, core, agent-* tsc -- Pure TypeScript compilation
frontend tsc Vite 6 React SPA, multi-entry (main + popup)
server tsc -- Node.js backend
electron tsc Vite 6 + vite-plugin-electron Main process + preload

Tech Stack

Technology Version Purpose
Node.js >=20.0.0 Runtime
TypeScript 5.9.3 Language
React 18.2.0 UI framework
Electron 33.4.11 Desktop shell
Vite 6.4.1 Frontend/Electron bundler
Tailwind CSS 4.1.18 Styling
Zod 4.3.6 Schema validation
Zustand 5.0.11 State management
Express 5.2.1 Web server

Running Modes

The app runs in two modes:

Desktop (Electron): npm run dev

  • Electron main process loads the frontend via Vite dev server
  • IPC transport between renderer and main process

Web: npm run dev:web

  • Server and Frontend run as separate processes
  • HTTP transport between browser and Express server
  • Uses AGENTAGE_CONFIG_DIR for isolated config

Test Infrastructure

Unit tests (Jest 30)

npm run test                 # All unit tests
npm run test:coverage        # With 70% coverage threshold

Configured in jest.config.cjs. Projects: shared, core, electron, frontend.

E2E tests (Playwright 1.58)

npm run test:e2e             # Default gate
npm run test:e2e -- --gate=ci           # CI gate (fast)
npm run test:e2e -- --gate=pull-request # PR gate (full)

Configured in playwright.config.ts with gate-based test selection via tests/config/gates.json.

Test gates

Gate When What it runs
ci Push to master smoke, navigation, projects-api, agents-api
pull-request PR validation smoke, navigation, visual, projects (api > web > visual), agents (api, web, visual)
pre-release Before release Full regression including electron tests
post-release After release Platform-specific installer validation

Test directory structure

tests/
├── smoke/                 App loads, heading visible
├── navigation/            Page routing
├── projects/
│   ├── api/               CRUD, git operations, settings
│   ├── web/               List, filters, detail, worktrees
│   ├── visual/            Screenshot comparisons
│   ├── electron/          Electron-specific
│   └── fixtures.ts        Project test fixtures
├── agents/
│   ├── api/               Registry, discovery, scanning
│   ├── web/               Agent list and detail UI
│   ├── visual/            Visual regression
│   └── fixtures.ts        Agent test fixtures
├── post-release/          Platform installer validation
├── config/                Gates, test config, test skills
├── framework/             Base fixtures, visual helpers
├── helpers/               Selectors (TID registry), test data
├── fixtures/              Page object fixtures
└── pages/                 Page object model classes

npm Scripts

Script Purpose
dev Start Electron dev mode
dev:web Start web dev (server + frontend)
build Full build pipeline (all packages in order)
type-check TypeScript validation across all packages
lint / lint:fix ESLint across all packages
test Jest unit tests
test:coverage Unit tests with 70% coverage threshold
test:e2e Playwright E2E tests (gate-aware)
verify type-check + lint + test + build
clean Remove dist/ and node_modules

Agent/Skill Discovery Paths

The system discovers agents from multiple sources:

Type Global Path Project Path
Agentage native ~/.agentage/skills/<name>/SKILL.md .agentage/skills/<name>/SKILL.md
Claude skill ~/.claude/skills/<name>/SKILL.md .claude/skills/<name>/SKILL.md
Claude command ~/.claude/commands/<name>.md .claude/commands/<name>.md
Agentage plugin Via plugin registry Via plugin registry
Claude plugin Via plugin registry Via plugin registry