# Getting Started

Welcome to ows-coda — the AI assistant for the Abacus royalties platform. Coda helps account managers, finance teams, and operations staff answer questions about accounts, contracts, revenue, and ledger balances by querying live backend services through a conversational interface. Instead of navigating multiple dashboards and reports, users ask questions in natural language and get answers backed by real data.

This guide walks you through everything you need to get up and running.

## Step 1: Prerequisites

- **Node >= 24** — install via `nvm` or `mise`
- **pnpm** — `npm install -g pnpm`
- **AWS credentials** with `bedrock:InvokeModel` permission
- (Optional) **Docker** for containerized dev/test
- (Optional) **Redis** for conversation persistence

## Step 2: Clone and run

```bash
git clone git@github.com:theorchard/ows-coda.git
cd ows-coda
for d in server client search runner platform; do cp apps/$d/.env.shadow apps/$d/.env; done
pnpm install
aws sso login --profile orchard-dev
pnpm dev              # backend on http://localhost:8080
pnpm dev:client       # frontend on http://localhost:5173 (proxies /api to backend)
```

Or run both at once with `pnpm dev:all`.

### Fast / lightweight iteration

`pnpm dev` starts 11 library build-watchers alongside the server. For day-to-day work on `apps/server` (where the agent/workflow code lives), use the lightweight path instead:

```bash
cp apps/server/.env.shadow apps/server/.env   # already configured to boot offline
pnpm dev:light        # builds libs ONCE, then watches only the server
# or pnpm dev:light:all to also run the client
```

The shipped `.env.shadow` boots with **no external services**: in-memory cache (blank `REDIS_URL`), no DB (blank `CODA_DB_*`), Snowflake/search/platform disabled, and **`CODA_DEV_AUTH_BYPASS=true`** so the API works without an Auth0 token (a fixed dev identity is injected; this flag is force-disabled in production). Only `aws sso login` is needed, and only for real Bedrock/AI calls. After editing a `packages/*` library, re-run `pnpm build:libs` (or `pnpm dev:light`) to pick it up.

## Step 3: Environment variables

Copy per-package `.env.shadow` files to `.env` — they're annotated templates with all expected variables. The `.env` files are gitignored and must never be committed.

- `apps/server/.env.shadow` → `apps/server/.env` (backend secrets, downstream URLs, Bedrock config)
- `apps/client/.env.shadow` → `apps/client/.env` (VITE\_\* vars for the React frontend)
- `apps/search/.env.shadow` → `apps/search/.env` (search service config — optional if running search separately)
- `apps/runner/.env.shadow` → `apps/runner/.env` (datasource runner config — optional)
- `apps/platform/.env.shadow` → `apps/platform/.env` (platform service config — optional)

Key variables:

| Variable                 | Required | Description                                            |
| ------------------------ | -------- | ------------------------------------------------------ |
| `OWS_ABACUS_ACCOUNT_URL` | Yes      | Account service base URL                               |
| `OWS_ROYALTIES_URL`      | Yes      | Royalties service base URL                             |
| `OWS_MONEYHUB_URL`       | Yes      | Financial service base URL                             |
| `OWS_PRODUCT_URL`        | Yes      | Product service base URL                               |
| `OWS_LEDGER_URL`         | Yes      | Ledger service base URL                                |
| `REDIS_URL`              | No       | Redis URL; blank → in-memory cache (stateless)         |
| `SENTRY_DSN`             | No       | Sentry DSN; blank → error reporting disabled           |
| `CODA_DEV_AUTH_BYPASS`   | No       | `true` skips Auth0 locally (force-disabled in prod)    |
| `GRAPHQL_GATEWAY_URL`    | No       | GraphQL gateway URL (enables GraphQL tools)            |
| `SNOWFLAKE_READER_*`     | No       | Snowflake reader pool config (enables Snowflake tools) |
| `CODA_DB_*`              | No       | Persistent DB config (Aurora MySQL)                    |
| `DD_TRACE_ENABLED`       | No       | Set `false` to disable Datadog locally                 |

See the full variable list in `apps/server/.env.shadow` and `apps/client/.env.shadow`.

## Step 4: Redis (optional)

Without Redis the service runs stateless — every request starts a fresh conversation. To enable persistence locally:

```bash
docker run -p 6379:6379 redis:7
# then in server/.env:
REDIS_URL=redis://localhost:6379
```

## Step 5: Docker (optional)

For a full containerized dev environment with MySQL, Redis, and HMR:

```bash
pnpm docker:up
```

This starts MySQL + Redis + Prisma migrations + Express server (tsx --watch) + Vite dev server (HMR). See [Docker](guides/docker.md) for the full command reference and architecture.

## Step 6: Claude Code setup (recommended)

Claude Code is the team's primary AI coding assistant. The repo ships with config files that set it up automatically.

1. **Install Claude Code** — available in Self Service, or install the VS Code extension (search "Claude Code" in Extensions)
2. **Open the repo** in Claude Code
3. **Connect MCP integrations** — run `/mcp` and complete the OAuth flow for each server:
   - **Notion** — workspace pages and databases
   - **Atlassian** — Jira issues and boards
   - **Sentry** — error tracking and issue investigation
4. **Install the Notion plugin** (optional but recommended):

```bash
/plugin marketplace add makenotion/claude-code-notion-plugin
/plugin install notion-workspace-plugin@notion-plugin-marketplace
```

MCP auth persists across sessions — re-auth only if tokens expire. Run `/mcp` anytime to check status.

### What's configured for you

- **`CLAUDE.md`** — project context loaded at the start of every session
- **`.mcp.json`** — MCP server connections (Notion, Atlassian, Sentry), project-scoped
- **`.claude/settings.json`** — shared settings (Notion plugin enabled)
- **`.claude/settings.local.json`** — gitignored, for personal overrides

### Tips

- Use `/mcp` to check MCP server status and re-authenticate if needed
- Use Notion skills like `/Notion:search` to find docs, `/Notion:create-page` to draft docs
- Jira is available via the Atlassian MCP server — Claude can search issues, read tickets, and more
- Sentry is available for error investigation — ask Claude to look up recent errors or analyze stack traces
- Personal settings go in `.claude/settings.local.json` (gitignored)

### Resources

- [Connecting to Notion MCP](https://developers.notion.com/guides/mcp/get-started-with-mcp)
- [Notion Plugin for Claude Code](https://github.com/makenotion/claude-code-notion-plugin)
- [Atlassian Remote MCP Server](https://support.atlassian.com/atlassian-rovo-mcp-server/docs/getting-started-with-the-atlassian-remote-mcp-server/)

## Step 7: Learn the codebase

| Doc                                           | What to read it for                                                   |
| --------------------------------------------- | --------------------------------------------------------------------- |
| [Architecture](architecture/overview.md)      | System design, request flow, design decisions, project structure      |
| [Tool Catalog](api/tool-catalog.md)           | All tools across 9 categories + 5 skills — what Coda can and can't do |
| [API Reference](api/server.md)                | Endpoints, SSE events, supported models and attachments               |
| [Search Architecture](architecture/search.md) | Search algorithms and ranking: BM25 + HNSW + glossary pipeline        |
| [Snowflake Views](snowflake-views.md)         | How Snowflake views are published and consumed by ows-coda            |

## Step 8: Make your first change

| Doc                                     | What to read it for                                          |
| --------------------------------------- | ------------------------------------------------------------ |
| [Development lifecycle (SDLC)](sdlc.md) | End-to-end flow: plan, design, develop, test, review, deploy |
| [Contributing](../CONTRIBUTING.md)      | Workflow, conventions, PR process, adding tools              |
| [Testing](guides/testing.md)            | Vitest, mocking, writing tests                               |
| [Deployment](operations/deployment.md)  | Jenkins pipeline, Docker stages, environment promotion       |

## Troubleshooting

Hit a snag? Check the [Runbook](operations/runbook.md) for common issues: Bedrock throttling, Redis failures, Snowflake connectivity, GraphQL errors, auth problems, missing env vars, Docker build problems.

## Quick reference

| Resource   | Link                                                                                   |
| ---------- | -------------------------------------------------------------------------------------- |
| Jira board | [COD Board](https://theorchard.atlassian.net/jira/software/c/projects/COD/boards/1318) |
| Slack      | `#abacus-devs`                                                                         |