---
title: Architecture and package boundaries
description: Locate the relevant package and follow a task through execution and validation.
lastVerified: 2026-10-23
---

# 6.10 Architecture and package boundaries

This page is for developers changing Teloa source. Locate the relevant package, then follow the user action, business state and execution result through the full path.

## Responsibilities along one work item

```text
User input -> React workspace -> Harness / RPC -> Business services -> PostgreSQL
                                  |
                                  -> Native sessions, models and tools
                                  |
Execution events -> Task / Run state and results -> Original conversation and task UI
```

Teloa preserves business ownership of employees, work, approvals and results; DSH supplies native execution. A model response, execution ending and business acceptance are separate facts.

## Where to make a change

| Directory | Responsibility | Typical changes |
| --- | --- | --- |
| `packages/contract` | Types, format readers and validation | Fields, templates, requests and responses |
| `packages/backend` | Persistence, transactions, idempotency and rules | Task state, fixed results and grants |
| `packages/harness-dsh` | Engine adaptation and tool authorization | Context, dispatch, stop and result return |
| `packages/client/ui-workbench` | Workspace UI and state presentation | Employees, groups, tasks, settings and drawers |
| `packages/client/ui-kit` | Shared UI components | Controls and common interaction containers |
| `packages/bundle` | Fixed plugin compositions and presets | Runtime composition and preset configuration |
| `packages/sdk` | External employee contract and client | Shared HTTP, SDK and MCP formats |
| `packages/cli` | Native installation and service lifecycle | Startup, stop, backup and upgrade |
| `packages/mcp-reference` | Read-only reference MCP service | Listing, versioned reads and denials |
| `packages/local-embedding` | Local retrieval adapter | Preparation, embeddings, indexes and search |

The AI Team, Agent Studio and Agent Harness [product layers](https://docs.teloa.ai/v/0.2.10/markdown/en/concepts/layers.md) explain product responsibilities; they do not map one-to-one to packages.

## Follow an employee call

Read these files in order for the external employee API:

1. `packages/sdk/contract.mjs`: request fields, states and results.
2. `packages/harness-dsh/src/employee-integration-host.ts`: HTTP/MCP authentication and dispatch.
3. `packages/backend/src/work/employee-integrations.ts`: fixed employee version, scope and permissions.
4. `packages/backend/src/work/employee-api-work.ts`: work, rounds, idempotency, results and events.
5. `packages/harness-dsh/src/task-runs.ts`: native preparation, start, reconciliation and stop.
6. `packages/client/ui-workbench/src/client/EmployeeIntegrationSettings.tsx`: owner integration management.

Run the [employee integration example](https://docs.teloa.ai/v/0.2.10/markdown/en/develop/employee-api.md) to observe the behavior. Follow the same work, Task and Run IDs; do not combine another work item's result with the task you are investigating.

## Change a cross-package field

For a new task field, update its contract and defaults, persistence, adapter parsing and client presentation. Add migration and compatibility reads where needed, then cover old data, new data and invalid values.

Changing a TypeScript type is insufficient: runtime readers may reject unknown fields. The UI must not bypass business services with direct database access.

## Extension points

- New working method: start with a [SKILL](https://docs.teloa.ai/v/0.2.10/markdown/en/develop/skills.md), usually without core changes.
- New external system: start with an [MCP app](https://docs.teloa.ai/v/0.2.10/markdown/en/develop/apps.md), enforcing service-side access and employee grants separately.
- New resource type: update readers, preview, import, sharing and tests, preserving subject restrictions.
- New execution component: preserve identity, grants, cancellation and provenance through [engine boundaries](https://docs.teloa.ai/v/0.2.10/markdown/en/develop/engine-integration.md).
- Local models: existing voice and retrieval setup is in the [settings guide](https://docs.teloa.ai/v/0.2.10/markdown/en/guides/settings.md); new providers need separate preparation, runtime and authorization verification.

Prepare an isolated [local environment](https://docs.teloa.ai/v/0.2.10/markdown/en/develop/local-development.md), then validate through [testing and contributing](https://docs.teloa.ai/v/0.2.10/markdown/en/develop/testing.md).