Repository package documentation

agentex/docs/docs/packages/agentex-backend/adapters.md

@@ -0,0 +1,58 @@
+## Backend: adapters (`src/adapters/`)
+
+Adapters are the concrete implementations of domain “ports” (repository interfaces, external services, and infrastructure clients). Adapters are where the backend talks to Postgres, MongoDB, Redis, Temporal, and external auth services.
+
+### Adapter families
+
+#### CRUD store (`src/adapters/crud_store/`)
+
+- **Purpose**: persistence implementation across SQL (Postgres) and documents (MongoDB).
+- **Key files**:
+  - `adapter_postgres.py`: SQLAlchemy-based implementation for relational entities.
+  - `adapter_mongodb.py`: MongoDB implementation for message-like collections.
+  - `port.py`: port/interface definitions used by higher layers.
+  - `exceptions.py`: adapter-specific errors.
+
+#### Streams (`src/adapters/streams/`)
+
+- **Purpose**: realtime updates and pub/sub over Redis Streams.
+- **Key files**:
+  - `adapter_redis.py`: Redis client implementation.
+  - `port.py`: stream adapter interface.
+
+#### Temporal (`src/adapters/temporal/`)
+
+- **Purpose**: access to Temporal as a workflow engine.
+- **Key files**:
+  - `adapter_temporal.py`: Temporal client wrapper.
+  - `client_factory.py`: consistent client construction.
+  - `port.py`: Temporal adapter interface.
+  - `exceptions.py`: Temporal adapter errors.
+
+#### HTTP (`src/adapters/http/`)
+
+- **Purpose**: outbound HTTP calls (e.g., to auth proxies or other services).
+- **Key files**:
+  - `adapter_httpx.py`: httpx-based client adapter.
+  - `port.py`: HTTP adapter interface.
+
+#### Authentication & authorization (`src/adapters/authentication/`, `src/adapters/authorization/`)
+
+- **Purpose**: integration with external identity/permissions systems.
+- **Key files**:
+  - `adapter_agentex_authn_proxy.py`: authentication proxy implementation.
+  - `adapter_agentex_authz_proxy.py`: authorization proxy implementation.
+  - `port.py`: interface definitions.
+  - `exceptions.py`: adapter errors.
+
+### Adding a new adapter
+
+When introducing a new integration:
+
+1. Define an interface in `src/domain/repositories/` or an adapter `port.py` (depending on whether it’s persistence or infrastructure).
+2. Implement the interface under `src/adapters/<family>/`.
+3. Wire it into dependency injection in `src/config/dependencies.py`.
+4. Add tests:
+   - unit tests for domain behavior using mocks
+   - integration tests for real dependency behavior (when practical)
+

agentex/docs/docs/packages/agentex-backend/api-layer.md

@@ -0,0 +1,62 @@
+## Backend: API layer (`src/api/`)
+
+The API layer translates HTTP requests into domain use-case calls and translates domain objects back into HTTP responses.
+
+### What lives here
+
+- **App wiring**: `src/api/app.py`
+  - Creates the FastAPI application.
+  - Registers middleware.
+  - Includes routers from `src/api/routes/`.
+  - Handles lifespan startup/shutdown hooks (dependency initialization).
+- **Routes**: `src/api/routes/*.py`
+  - Resource-oriented routers (agents, tasks, messages, spans, state, events, schedules, etc.).
+  - Request validation and response shaping via schema models.
+  - Delegation to use cases in `src/domain/use_cases/`.
+- **Schemas**: `src/api/schemas/*.py`
+  - Pydantic models for request/response payloads.
+  - Versioning/backwards-compatibility (when needed) should be handled here instead of leaking into domain code.
+- **Middleware**:
+  - `src/api/authentication_middleware.py`: request authentication and principal context population.
+  - `src/api/RequestLoggingMiddleware.py`: request/response logging.
+  - `src/api/middleware_utils.py`: shared middleware helpers.
+- **Auth cache**: `src/api/authentication_cache.py`
+  - Caches authentication lookups (used by auth middleware and/or adapters).
+
+### Routers (HTTP resources)
+
+The backend registers these routers in `src/api/app.py`:
+
+- **`agents.py`**: agent CRUD/registration, ACP-related agent metadata.
+- **`tasks.py`**: task creation, listing, and lifecycle operations.
+- **`messages.py`**: task message creation and retrieval (including streaming patterns).
+- **`spans.py`**: execution trace spans (OpenTelemetry-style).
+- **`states.py`**: agent/task state storage (key/value style state).
+- **`events.py`**: event ingestion and retrieval for agent/task workflows.
+- **`agent_task_tracker.py`**: “agent task tracker” endpoints used to coordinate long-running/background work.
+- **`agent_api_keys.py`**: agent API key management.
+- **`deployment_history.py`**: deployment/version history for agents.
+- **`schedules.py`**: schedules for recurring or deferred task execution.
+- **`health.py`**: health and readiness endpoints.
+
+### Dependency flow
+
+API routes should depend only on:
+
+- **Domain use cases** (`src/domain/use_cases/*`), and
+- **FastAPI dependencies** (injected handles to adapters via `src/config/dependencies.py`)
+
+Routes should *not* directly depend on concrete adapter implementations (Postgres/Mongo/Redis/etc.). That keeps the domain and test layers isolated.
+
+### Adding a new endpoint (pattern)
+
+When adding a new endpoint, prefer this sequence:
+
+1. Define or extend domain entities in `src/domain/entities/`.
+2. Add/extend repository interface(s) in `src/domain/repositories/`.
+3. Implement the repository in `src/adapters/`.
+4. Add a use case in `src/domain/use_cases/`.
+5. Add request/response models in `src/api/schemas/`.
+6. Add a router in `src/api/routes/` and include it in `src/api/app.py`.
+7. Add unit/integration tests in `tests/unit/` and `tests/integration/`.
+

agentex/docs/docs/packages/agentex-backend/config-and-deps.md

@@ -0,0 +1,45 @@
+## Backend: configuration & dependency wiring (`src/config/`)
+
+The backend uses explicit dependency wiring to keep framework concerns (FastAPI) and infrastructure concerns (databases, Redis, Temporal) separated from domain logic.
+
+### What lives here
+
+- **Environment variables**: `src/config/environment_variables.py`
+  - Defines and validates settings that control service behavior (DB URLs, Temporal address, Redis URL, Mongo settings, auth proxy settings, etc.).
+  - Prefer adding new settings here and reading them via a typed settings object rather than calling `os.getenv` throughout the codebase.
+- **Global dependencies**: `src/config/dependencies.py`
+  - Creates long-lived clients/engines (SQLAlchemy engine, Mongo client, Redis client, Temporal client).
+  - Exposes dependency providers for FastAPI routes (e.g., “read/write DB engine”).
+  - Manages startup/shutdown lifecycle (connect, health checks, close pools).
+- **MongoDB indexes**: `src/config/mongodb_indexes.py`
+  - Central place to define required indexes for MongoDB collections.
+  - Index creation is typically performed during startup.
+
+### Common environment variables
+
+The backend reads most configuration via environment variables. Common ones include:
+
+- **`ENVIRONMENT`**: `development`, `staging`, or `production`.
+- **`DATABASE_URL`**: Postgres connection string.
+- **`MONGODB_URI` / `MONGODB_DATABASE_NAME`**: Mongo connection and database name.
+- **`REDIS_URL`**: Redis connection string (required for realtime streaming/subscriptions).
+- **`TEMPORAL_ADDRESS` / `TEMPORAL_NAMESPACE`**: Temporal server configuration.
+- **`AGENTEX_AUTH_URL`**: authentication proxy URL (if enabled).
+- **`ALLOWED_ORIGINS`**: CORS configuration.
+
+### How dependencies are used
+
+- API routes request dependencies using FastAPI’s dependency injection.
+- Use cases and services accept repositories/ports (interfaces) or already-wired adapters.
+- Adapters own concrete client objects (sqlalchemy sessions/engines, pymongo clients, redis clients, temporal clients).
+
+### Adding a new dependency
+
+When adding a new infrastructure dependency:
+
+1. Add configuration in `environment_variables.py`.
+2. Create the client/engine in `dependencies.py`.
+3. Expose it through a FastAPI dependency provider if routes need it.
+4. Ensure you close it on shutdown (connection pools, aio clients).
+5. Add or update health checks (if the service is required for startup).
+

agentex/docs/docs/packages/agentex-backend/database-and-migrations.md

@@ -0,0 +1,31 @@
+## Backend: database & migrations (`agentex/database/`)
+
+The backend persists relational data in PostgreSQL using SQLAlchemy, with schema migrations managed by Alembic.
+
+### What lives here
+
+- **Alembic config**: `database/migrations/alembic.ini`
+- **Alembic environment**: `database/migrations/alembic/env.py`
+- **Migration scripts**: `database/migrations/versions/*.py`
+- **Migration history export**: `database/migrations/migration_history.txt`
+
+### When you need a migration
+
+Create a migration whenever you change:
+
+- SQLAlchemy models / relational schema
+- constraints, indexes, or columns for relational entities
+
+From `agentex/`:
+
+```bash
+make migration NAME="describe_change"
+make apply-migrations
+```
+
+### MongoDB collections
+
+MongoDB is used for document-oriented storage (not managed by Alembic). Index requirements are usually defined in:
+
+- `src/config/mongodb_indexes.py`
+

agentex/docs/docs/packages/agentex-backend/domain-layer.md

@@ -0,0 +1,34 @@
+## Backend: domain layer (`src/domain/`)
+
+The domain layer contains the application’s core business logic. It is designed to be framework-agnostic: no FastAPI objects, no database drivers, no Redis/Temporal clients.
+
+### What lives here
+
+- **Entities (`src/domain/entities/`)**
+  - Domain objects that represent the system’s state and payloads: agents, tasks, messages, spans, events, states, schedules, and supporting types.
+  - These are the types your use cases should speak.
+- **Repository interfaces (`src/domain/repositories/`)**
+  - Abstract “ports” for persistence and external I/O (agents repository, task repository, message repository, span repository, etc.).
+  - Adapters implement these interfaces.
+- **Services (`src/domain/services/`)**
+  - Reusable domain logic that doesn’t belong to a single use case (authorization, task/message orchestration, scheduling rules, ACP interactions).
+- **Use cases (`src/domain/use_cases/`)**
+  - Application operations invoked by the API layer.
+  - Use cases coordinate repository calls, enforce invariants, and return domain entities.
+- **Exceptions (`src/domain/exceptions.py`)**
+  - Domain-level errors that can be mapped to HTTP responses in the API layer.
+
+### Typical call flow
+
+1. A route handler validates the incoming request via `src/api/schemas/*`.
+2. The route invokes a use case in `src/domain/use_cases/*`.
+3. The use case calls repository interfaces and/or services.
+4. Adapter implementations satisfy repository calls and return domain entities.
+5. The route serializes the domain result into a response schema.
+
+### Where to put new logic
+
+- **New business rule** shared across multiple operations: add a domain service.
+- **New operation** that changes user-visible behavior: create a new use case (or extend an existing one).
+- **New persistence need**: extend a repository interface and update the adapter(s).
+

agentex/docs/docs/packages/agentex-backend/index.md

@@ -0,0 +1,50 @@
+## `agentex/` (Agentex Backend)
+
+The backend is a FastAPI service that provides the Agentex HTTP API, orchestrates long-running work with Temporal, and persists agent/task state across:
+
+- **PostgreSQL**: relational data (agents, tasks metadata, API keys, deployment history).
+- **MongoDB**: flexible documents (task messages and related content).
+- **Redis**: streams and caching for realtime updates and subscriptions.
+
+The codebase is organized using a clean-architecture / ports-and-adapters style:
+
+- **API layer (`src/api/`)**: HTTP concerns (routes, schemas, middleware). Delegates to use cases.
+- **Domain layer (`src/domain/`)**: business logic, entities, repository interfaces, services, use cases.
+- **Adapters (`src/adapters/`)**: implementations of ports for databases, Redis streams, Temporal, HTTP clients, and auth proxies.
+- **Config (`src/config/`)**: environment variables, global dependency wiring, startup/shutdown initialization.
+- **Temporal (`src/temporal/`)**: workers, workflows, and activities used for backend background jobs.
+- **Utilities (`src/utils/`)**: shared helpers (ids, pagination, logging, timestamp, http clients).
+
+### Entry points
+
+- **FastAPI app**: `src/api/app.py`
+- **HTTP routes**: `src/api/routes/` (mounted by the app)
+- **Temporal worker**: `src/temporal/run_worker.py`
+
+### Local development
+
+From `agentex/`:
+
+```bash
+uv sync --group dev
+docker compose up --build
+```
+
+Useful commands (see `agentex/Makefile` for the authoritative list):
+
+```bash
+make dev
+make test
+make serve-docs
+```
+
+### Public surface area
+
+The backend’s public interfaces are:
+
+- **HTTP API** served by FastAPI (see `src/api/routes/*` and the OpenAPI docs at `/swagger`).
+- **WebSocket / streaming updates** used by the UI for realtime task/message updates.
+- **Temporal workflows and activities** used for durable background execution.
+
+Internal modules (domain + adapters) are meant to be imported by the server only; downstream clients should use the HTTP API or the Agentex SDK.
+

agentex/docs/docs/packages/agentex-backend/temporal.md

@@ -0,0 +1,28 @@
+## Backend: Temporal (`src/temporal/`)
+
+Temporal is used to run durable background workflows (long-running, retriable, stateful processes). The backend typically uses Temporal for:
+
+- background health checks
+- durable execution patterns for agent task orchestration (when using a Temporal-based ACP)
+
+### What lives here
+
+- **Workflows**: `src/temporal/workflows/`
+  - Workflow definitions (stateful orchestration).
+- **Activities**: `src/temporal/activities/`
+  - Side-effecting operations invoked by workflows (I/O, network calls, database operations).
+- **Worker runner**: `src/temporal/run_worker.py`
+  - Starts a worker process to poll a task queue and execute workflows/activities.
+- **Workflow runner(s)**: `src/temporal/run_healthcheck_workflow.py`
+  - Convenience entrypoints for running specific workflows.
+
+### Design guidelines
+
+- Workflows should be deterministic; keep I/O in activities.
+- Prefer passing small, serializable payloads between workflow/activity boundaries.
+- Keep activity interfaces stable; treat them similarly to internal APIs.
+
+### Operating locally
+
+Temporal is provided by Docker Compose when running `make dev` in `agentex/`.
+

agentex/docs/docs/packages/agentex-backend/testing.md

@@ -0,0 +1,35 @@
+## Backend: testing (`agentex/tests/`)
+
+The backend test suite is organized into unit and integration tests, with shared fixtures to reduce setup overhead.
+
+### Test types
+
+- **Unit tests**: `tests/unit/`
+  - Fast, isolated, heavy use of mocks/fakes.
+  - Focus on domain logic (use cases, services), repository interface behavior, and utility functions.
+- **Integration tests**: `tests/integration/`
+  - Exercise the HTTP API and real infrastructure dependencies.
+  - Use testcontainers to spin up Postgres/Redis/Mongo as needed.
+
+### Fixtures
+
+- `tests/fixtures/`: common fixtures (containers, databases, repositories, services).
+- `tests/integration/fixtures/`: integration-specific fixtures (test client, environment helpers).
+
+### Running tests
+
+From `agentex/`:
+
+```bash
+make test
+make test-unit
+make test-integration
+```
+
+To run a single file or a subset, use `FILE=` or `NAME=`:
+
+```bash
+make test FILE=tests/unit/test_foo.py
+make test NAME=crud
+```
+

agentex/docs/docs/packages/agentex-ui/index.md

@@ -0,0 +1,43 @@
+## `agentex-ui/` (Agentex UI)
+
+The UI is a Next.js application (App Router) that provides a developer interface for:
+
+- browsing and selecting agents
+- creating tasks and monitoring task state
+- chatting with agents (including streaming responses)
+- inspecting execution traces/spans
+
+### Tech stack
+
+- **Next.js** 15 (App Router) + **React** 19
+- **TypeScript**
+- **Tailwind CSS** + Radix UI primitives / shadcn-style components
+- **React Query** for server state and caching
+
+### Entry points
+
+- **App shell**: `app/layout.tsx`
+- **Main page**: `app/page.tsx`
+- **Primary UI composition**: `components/agentex-ui-root.tsx` and `components/primary-content/*`
+
+### Data access
+
+The UI treats the backend as the source of truth and uses:
+
+- REST/HTTP calls to fetch lists and details (agents, tasks, messages, spans).
+- WebSocket subscriptions for realtime task updates (especially for async agents).
+
+Most data access is wrapped behind hooks in `hooks/` (React Query + subscription helpers).
+
+### Running locally
+
+From `agentex-ui/`:
+
+```bash
+npm install
+cp example.env.development .env.development
+npm run dev
+```
+
+The backend should be running separately (see `agentex/` docs).
+