# Software Development Lifecycle

How features move from idea to production in ows-coda.

```mermaid
flowchart LR
    plan[Plan] --> design[Design] --> develop[Develop] --> test[Test] --> review[Review] --> merge[Merge] --> deploy[Deploy] --> monitor[Monitor]
```

## 1. Plan

Every piece of work starts with a Jira ticket in the [COD project](https://theorchard.atlassian.net/jira/software/c/projects/COD/boards/1318).

- **Single task** — create a COD ticket with `labels: ["Coda"]`
- **Multi-task feature** — create a Jira Epic first, then child tickets per logical chunk
- **Required fields** — Initiative (`customfield_12481`) and Accounting Initiative (`customfield_13833`)

For significant features, write a PRD in `docs/decisions/prds/` before starting design. Existing PRDs: [sandbox-engine](decisions/prds/sandbox-engine.md), [dashboards](decisions/prds/dashboards.md), [enterprise-permissions](decisions/prds/enterprise-permissions.md), [message-feedback](decisions/prds/message-feedback.md), [offline-client](decisions/prds/offline-client-cursor-pagination.md), [auth-error-page](decisions/prds/auth-error-page.md).

## 2. Design

Write a Technical Reference Document (TRD) in `docs/decisions/trds/` for any work that changes architecture, adds a service, or introduces non-trivial patterns. TRDs capture the _why_ — rationale, alternatives explored, and decision log. See the [TRD index](decisions/trds/README.md) for all existing TRDs.

For implementation-level design, specs and plans are kept locally (gitignored — never commit).

## 3. Develop

### Branch

```bash
git checkout -b COD-1234_short_description
```

Branch naming: `COD-<ticket>_description` or `NOTICKET_description`.

### Environment

```bash
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:all    # server on :8080, client on :5173
```

Or use Docker: `pnpm docker:up`. See [Docker](guides/docker.md) for profiles and troubleshooting.

### Coding

Follow the conventions in [CLAUDE.md](../CLAUDE.md#code-conventions) and [CONTRIBUTING.md](../CONTRIBUTING.md#code-conventions). Key points:

- Constructor injection for dependencies
- Shared code goes in `packages/common/`
- Switch defaults throw
- No `I` prefix on interfaces
- Vitest for all tests (`vi.fn`, `vi.mock`)

### Commits

```
COD-1234 type(scope): message
```

Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`. When working from a plan, squash steps into logical groups rather than one commit per task.

## 4. Test

Three test tiers, all using Vitest:

| Tier            | What it tests                       | Infrastructure                   | Run command                    |
| --------------- | ----------------------------------- | -------------------------------- | ------------------------------ |
| **Unit**        | Individual functions, classes       | All mocked                       | `pnpm test:unit`               |
| **Functional**  | Full Express stack, DB interactions | Real MySQL + Redis, FakeProvider | `pnpm docker:test:functional`  |
| **Integration** | HTTP against running services       | Real MySQL + services            | `pnpm docker:test:integration` |

Run targeted tests during development:

```bash
pnpm --filter @coda/server-app test:unit                  # one package
pnpm exec vitest run cache-store                           # one test file
pnpm --filter @coda/server-app test:functional             # functional (needs DB)
```

Write comprehensive tests immediately after each implementation task — unit tests cover happy path, edge cases, error paths, and boundary conditions. See [Testing](guides/testing.md) for mocking patterns, test structure, and the FakeProvider.

### Automated checks on commit and push

| Hook            | Trigger      | What runs                                                                    |
| --------------- | ------------ | ---------------------------------------------------------------------------- |
| **lint-staged** | `git commit` | Prettier + ESLint on staged `.ts`/`.tsx` files                               |
| **post-commit** | After commit | Auto-formats committed files, amends if changed                              |
| **pre-push**    | `git push`   | Audit + format check + lint + typecheck + unit tests (all affected packages) |

The pre-push hook is intentionally slow — let it run. It checks only packages changed since `remote/master`.

## 5. Review

### Pull request

```bash
git push -u upstream COD-1234_short_description
gh pr create --title "COD-1234: Short description"
```

PR title format: `COD-<ticket>: Short description`. Use the Epic ticket for PRs spanning an entire Epic.

### Review checklist

- `pnpm typecheck` passes with zero errors
- `pnpm test` passes with adequate coverage
- No `any` types (use `unknown` + type guards)
- New tools have tests and updated [Tool Catalog](api/tool-catalog.md)
- No secrets committed (`.env` files are gitignored)

### Ephemeral environments

For pre-merge testing against real infrastructure, comment on the PR:

```
ephemeral deploy       # create (7-day TTL)
ephemeral deploy 15d   # custom TTL
ephemeral destroy      # tear down
ephemeral list         # show active environments
```

Each environment gets its own Fargate service and MySQL schema. See [Ephemeral Environments](operations/ephemeral-environments.md).

## 6. CI

Jenkins runs on every push and PR, in parallel:

| Stage      | What                                                                          |
| ---------- | ----------------------------------------------------------------------------- |
| Compliance | Internal policy validation                                                    |
| SAST       | Static application security testing                                           |
| SonarQube  | Code quality analysis                                                         |
| Unit tests | `docker compose up lint-and-test` — ESLint + typecheck + Vitest with coverage |

All stages must pass before a PR can merge.

## 7. Deploy

```mermaid
flowchart LR
    merge[Merge to master] --> build[Docker build + ECR push] --> scan[Container vulnerability scan] --> qa[Deploy to QA]
    qa -.-> prod[Production]
```

| Environment    | Trigger                    | Infrastructure                   |
| -------------- | -------------------------- | -------------------------------- |
| **Local**      | Manual (`pnpm dev`)        | Points to QA backends via `.env` |
| **QA**         | Auto on merge to `master`  | Fargate in `us-east-1`           |
| **Production** | Manual / separate pipeline | Separate deploy step             |

QA auto-deploys via Jenkins: Docker build → ECR push → vulnerability scan → Fargate update. See [Deployment](operations/deployment.md) for Docker build stages, rollback procedures, and troubleshooting.

Infrastructure is managed in the `terraform-infra` repo. See [CLAUDE.md Infrastructure](../CLAUDE.md#infrastructure-terraform) for module versions and paths.

## 8. Monitor

| Tool           | What it covers                                                          |
| -------------- | ----------------------------------------------------------------------- |
| **Datadog**    | APM traces, infrastructure metrics, log aggregation, service dashboards |
| **Sentry**     | Error tracking, stack traces, release health                            |
| **CloudWatch** | Fargate task logs, ECS service events                                   |

Datadog dashboards and monitors are provisioned via Terraform (`terraform-datadog` modules). Structured JSON logging with request-scoped context (requestId, identityHash, conversationId) enables Datadog faceting. See the [Logging TRD](decisions/trds/logging-improvements.md).

### Rollback

If a QA deployment introduces a regression:

1. Identify the last good commit SHA from ECR image tags or Jenkins history
2. Redeploy the previous Fargate task definition
3. Check whether any included DB migration is backwards-compatible

See [Deployment — Rollback](operations/deployment.md#rollback) for commands. For common operational issues, see the [Runbook](operations/runbook.md).

## Quick reference

| What         | Where                                                                                  |
| ------------ | -------------------------------------------------------------------------------------- |
| Jira board   | [COD Board](https://theorchard.atlassian.net/jira/software/c/projects/COD/boards/1318) |
| PRDs         | `docs/decisions/prds/`                                                                 |
| TRDs         | `docs/decisions/trds/` ([index](decisions/trds/README.md))                             |
| Architecture | [Architecture overview](architecture/overview.md)                                      |
| Contributing | [CONTRIBUTING.md](../CONTRIBUTING.md)                                                  |
| Testing      | [Testing guide](guides/testing.md)                                                     |
| Deployment   | [operations/deployment.md](operations/deployment.md)                                   |
| Docker       | [guides/docker.md](guides/docker.md)                                                   |
| Runbook      | [operations/runbook.md](operations/runbook.md)                                         |
| Roadmap      | [roadmap.md](roadmap.md)                                                               |
| Todos        | [todos.md](todos.md)                                                                   |