# ows-coda Standalone AI agent for the Abacus royalties platform. Uses AWS Bedrock (Claude) with tool-use, Redis conversation caching, and an Express API server with a React/Vite client. ## Packages ### Apps (deployable services) | Path | Name | Description | | ---------------- | ------------------------ | -------------------------------------------------- | | `apps/server/` | `@coda/server-app` | Express API + AI agent loop | | `apps/client/` | `@coda/client-app` | React/Vite frontend — uses **Vitest**, not Jest | | `apps/search/` | `@coda/search-service` | Hybrid search microservice (ConnectRPC, BM25+HNSW) | | `apps/runner/` | `@coda/runner-service` | Datasource runner service (WIP — COD-90) | | `apps/platform/` | `@coda/platform-service` | Platform service (auth, tenancy, permissions) | ### Packages (shared libraries) | Path | Name | Description | | --------------------------- | ----------------------- | ------------------------------------------------------------------------- | | `packages/async/` | `@coda/async` | Async patterns: circuit breaker, retry, semaphore, throttlers | | `packages/data-structures/` | `@coda/data-structures` | Generic data structures: heaps, trees, graphs, queues, stacks, algorithms | | `packages/search/` | `@coda/search` | Search engine: BM25, HNSW, trie, hybrid search, scoring | | `packages/common/` | `@coda/common` | Graph, storage, redis, crypto, utilities | | `packages/sandbox/` | `@coda/sandbox` | Isolated code execution engine (isolated-vm) | | `packages/api-common/` | `@coda/api-common` | Shared pagination protos, RPC utilities (callRpc, RpcResult) | | `packages/core-api/` | `@coda/core-api` | REST types, HTTP client, proto-generated ConnectRPC services | | `packages/admin-api/` | `@coda/admin-api` | Admin ConnectRPC services (access, identity, tenancy, RBAC) | | `packages/search-api/` | `@coda/search-api` | Search ConnectRPC client + proto definitions | | `packages/runner-api/` | `@coda/runner-api` | Runner ConnectRPC client + proto definitions | | `packages/tools-api/` | `@coda/tools-api` | Tool service proto definitions | | `packages/datasources-api/` | `@coda/datasources-api` | Datasource service proto definitions | | `packages/dashboards-api/` | `@coda/dashboards-api` | Dashboard service proto definitions | | `packages/db/` | `@coda/db` | Prisma ORM (Aurora MySQL) | | `packages/extensions/` | `@coda/extensions` | Domain glossary data (GraphQL + Snowflake) | ## Prerequisites - Node >= 24, pnpm - AWS credentials for Bedrock: `aws sso login --profile orchard-dev` - Copy env templates: `cp apps/server/.env.shadow apps/server/.env && cp apps/client/.env.shadow apps/client/.env && cp apps/search/.env.shadow apps/search/.env` - `.env` is gitignored — never commit it ## Commands ```bash pnpm dev # backend on http://localhost:8080 (tsx --watch) pnpm dev:client # Vite on http://localhost:5173 (proxies /api to backend) pnpm dev:all # both concurrently pnpm test # lint + unit tests with coverage (all packages) pnpm test:unit # Jest/Vitest only (no lint) pnpm lint # ESLint across all packages pnpm typecheck # tsc --noEmit across all packages pnpm format # Prettier auto-fix pnpm build # db:generate → server pnpm build:libs # build all library packages (packages/*) pnpm build:api # build @coda/core-api (required before cross-package typecheck) pnpm db:generate # generate Prisma client pnpm db:migrate # run pending migrations pnpm docker:up # full Docker dev env (MySQL + Redis + server + client) ``` ## Workflow See [Contributing](CONTRIBUTING.md) for the full workflow: tickets, branch naming, commit messages, PR titles, hooks, and CI. Quick reference: - **Branches:** `COD-1234_short_description` or `NOTICKET_description` - **Commits:** `COD-1234 type(scope): message` - **PRs:** `COD-1234: Short description` - **Tickets:** always create a Jira ticket first; `labels: ["Coda"]`, project key: **COD** - **Pre-push hooks** run audit + lint + typecheck + unit tests — intentionally slow; let it run - **Specs and plans:** save to `docs/superpowers/specs/` or `docs/superpowers/plans/` — gitignored, never commit them ## Infrastructure (Terraform) AWS infrastructure is managed in a separate repo (`terraform-infra`). Assume it's a sibling of this repo (i.e., `../terraform-infra/`). If not found, ask the user for the location. Terraform changes always go in a separate PR to that repo. Key conventions for `terraform-infra/qa/ows-coda/`: - **Flat file per concern** — one `.tf` file per service/feature (e.g., `platform.tf`, `runner.tf`, `api-gateway.tf`) - **Secrets Manager** — use the org's shared secrets module, never inline `aws_secretsmanager_secret`; values are set in console, never in Terraform; use AWS-managed KMS key (`aws/secretsmanager`), not custom KMS — custom keys break the org's daily backup process - **Ephemeral gating** — `count = local.is_ephemeral ? 0 : 1` or `local.create_X = !local.is_ephemeral` - **Route53** — use `provider = aws.networking` directly on records; reuse `data.aws_route53_zone.theorchard_io[0]` from `ecs_ec2.tf` See [Infrastructure](docs/operations/infrastructure.md) for directory layout, module versions, and environment details. ## Sub-agent Permissions Sub-agents are **read-only** — they have no access to `Edit`, `Write`, or any file-modifying tools. Only dispatch sub-agents for research, search, analysis, and review tasks. All code changes must be made by the orchestrator (main agent) directly. ## Safety Rules - **No file deletion without explicit confirmation** — list what will be deleted and wait for user approval; untracked files have no git recovery path - **No renaming shims** — when renaming methods, types, or modules, remove old names entirely and update all callsites; no `@deprecated` aliases or backward-compat re-exports - **Never stage `docs/superpowers/`** — the directory is gitignored; if files somehow get tracked, drop those commits before opening a PR ## Code Conventions See the full [Code Style Guide](docs/guides/code-style.md) for detailed conventions with examples. Key principles: - **Interfaces over implementations** — depend on `KeyValueStore`, not `RedisClient`; no `I` prefix - **Null object pattern** — `NullCache`, `NullKeyValueStore` over optional properties with guards - **Check existing shared packages before writing helpers** — `@coda/async` (async patterns), `@coda/data-structures` (data structures), `@coda/search` (search/NLP), `@coda/common` (graph, storage, redis, crypto, utils); extract reusable logic to the appropriate package - **Constructor DI** — inject interfaces, not concrete classes - **Named functions over anonymous callbacks** — aids readability, stack traces, and testability - **Switch defaults throw** — never silently fall back; exhaustive pattern matching - **`Iterable` for collection inputs** — if a parameter only iterates, accept any iterable - **Structural validation only** — generic utilities validate shape (`assertPositiveInt`); policy limits belong in config/Zod - **Handlers own availability** — `enabled()` predicates live in the handler, not in external registries ## Documentation - [Docs map](docs/README.md) — start here for all documentation - [Getting Started](docs/getting-started.md) — onboarding, setup, Claude Code - [Architecture](docs/architecture/overview.md) — system design, decisions, project structure - [Testing](docs/guides/testing.md) — Vitest, mocking, writing tests - [Code Style](docs/guides/code-style.md) — design principles, naming, patterns - [Tool Catalog](docs/api/tool-catalog.md) �� all tools and skills - [API Reference](docs/api/server.md) — endpoints, SSE events, models - [Docker](docs/guides/docker.md) — local Docker environment - [MCP Server](docs/guides/mcp-server.md) — expose tools to Claude Code/Desktop via MCP - [Infrastructure](docs/operations/infrastructure.md) — Terraform modules, environments - [Contributing](CONTRIBUTING.md) — workflow, conventions, PR process - [Todos](docs/todos.md) — project todo list ## Development workflow - **Brainstorm before new features** — use `/superpowers:brainstorm` before writing code for any new feature or significant behavior change - **Plan multi-step work** — use `/superpowers:writing-plans` for tasks spanning multiple files or packages; save plans to `docs/superpowers/plans/` - **Use worktrees for isolation** — feature branches with risk of conflicting with in-progress work should use git worktrees - **PR review before merge** — run `/pr-review-toolkit:review-pr` before opening PRs ## Claude Code setup Install plugins once — they persist across sessions: ``` /plugin install atlassian # Jira skills (/atlassian:*) /plugin install pup # Datadog monitoring (/pup:*) /plugin install playwright # Browser automation (/pw:*, /playwright-cli) /plugin install superpowers # Dev workflow skills (/superpowers:*) /plugin install pr-review-toolkit # PR review (/pr-review-toolkit:*) /plugin install commit-commands # Git workflow (/commit-commands:*) ``` MCP integrations (optional): `atlassian`, `notion`, and `sentry` plugins provide MCP server access. Run `/mcp` and complete the OAuth flow for each — persists across sessions. ## Team links - **Jira board:** https://theorchard.atlassian.net/jira/software/c/projects/COD/boards/1318 - **Team page:** https://home.atlassian.com/o/d431290j-06k8-1ad7-7448-k323d3dd03b2/people/team/6250efae-c21a-44ab-b570-c7a429d32794?cloudId=f214063a-38b5-4cf9-9225-b101f1ff31d0