# cbb-sign — Software Development Life Cycle

**Parent document:** [CBB_SDLC.md](../../../CBB_Corporate/03_-_Confidential/Process/CBB_SDLC.md) — CBB-wide master. This document extends the master for the cbb-sign project.
**Owner:** Cold Bore Ballistics LLC
**Product:** cbb-sign (internal document signing platform)
**Status:** Active

---

## Purpose

This document defines the cbb-sign-specific software development process. It covers the technology stack, repository structure, branching conventions, version numbering, release checklist, and platform-specific practices. All CBB-wide policies (roles, machine setup, credential controls, dev workflow, requirements management, test principles, release principles, bug management, documentation standards, security, issue tracking) are governed by `CBB_SDLC.md` and are not duplicated here.

---

## Table of Contents

1. [Product Overview](#1-product-overview)
2. [Development Environment — cbb-sign Stack](#2-development-environment--cbb-sign-stack)
3. [Repository Structure](#3-repository-structure)
4. [Branching Strategy](#4-branching-strategy)
5. [Requirements Management — SPEC](#5-requirements-management--spec)
6. [Testing Strategy](#6-testing-strategy)
7. [Release Process](#7-release-process)
8. [Infrastructure](#8-infrastructure)
9. [Tools Reference](#9-tools-reference)

---

## 1. Product Overview

`cbb-sign` is a CBB-branded internal document signing platform. It wraps a self-hosted DocuSeal OSS instance (private fork) with:

- A web UI for internal users (Entra ID SSO, role-based access)
- A FastAPI backend that handles AAA, orchestrates DocuSeal, Gotenberg, OneDrive, and audit trail
- Post-sign automation: signed PDF renamed with signer name + Zulu timestamp, filed to OneDrive
- Immutable audit trail: append-only PostgreSQL events + Azure Blob WORM completion certificates
- CBB-branded DocuSeal fork (logo, colors, email templates); wet signature override support

DocuSeal is the signing engine. cbb-sign is the wrapper — it does not duplicate DocuSeal's signing UI.

---

## 2. Development Environment — cbb-sign Stack

General machine setup requirements are defined in CBB_SDLC.md §3. The cbb-sign stack adds:

### 2.1 API (`cbb-sign-api`)

| Component | Detail |
|---|---|
| Language | Python 3.12+ |
| Framework | FastAPI |
| Auth | MSAL (Entra ID SSO) |
| ORM | SQLAlchemy + Alembic migrations |
| Database | PostgreSQL (Azure VNet — `cbb_sign` database on shared server) |
| Container | Docker |
| Package manager | `uv` |
| Testing | pytest + httpx |

### 2.2 Web UI (`cbb-sign-ui`)

| Component | Detail |
|---|---|
| Language | TypeScript |
| Framework | Next.js (React) |
| Auth | MSAL React |
| Styling | Tailwind CSS |
| Container | Docker |
| Package manager | pnpm |
| Testing | Vitest + Playwright (E2E) |

### 2.3 DocuSeal Fork (`docuseal`)

| Component | Detail |
|---|---|
| Language | Ruby on Rails |
| Fork base | DocuSeal OSS (AGPL-3.0, private fork — upstream remote maintained) |
| Scope of changes | CBB branding (logo, colors, email templates); wet signature signer flag |
| Image | Built + pushed to `crcbbprod.azurecr.io/engross/engross:cbb-<version>` |

---

## 3. Repository Structure

| Repo | Purpose | Visibility | Org / account |
|---|---|---|---|
| `cbb-sign` | Monorepo: `api/` (FastAPI), `ui/` (Next.js) | Private | `ColdBoreBallistics` |
| `engross` | **Engross** — renamed, modified fork of DocuSeal OSS (AGPL-3.0) — CBB branding + wet-sig flag only | **Public** | `ColdBoreBallistics` (public, alongside the bt-bridge-* repos) |

The `cbb-sign` monorepo is private in the `ColdBoreBallistics` GitHub org. Both repos are checked out locally under the lowercase grouping directory `cbb-sign/` (i.e., `cbb-sign/cbb-sign` and `cbb-sign/engross`). Note the deliberate casing split: the local repo-group dir and the repos are lowercase `cbb-sign`/`engross`; the OneDrive **docs** namespace is `CBB_Sign/`; the Jira project key is `SIGN`.

**The DocuSeal fork — named `Engross` — is PUBLIC and lives in the `ColdBoreBallistics` org** (host decision revised 2026-06-12), alongside CBB's other public FOSS repos (bt-bridge-*). AGPL-3.0 §13 compliance is satisfied by openly offering the modified source (see SPEC §1.3). The name does not present as "DocuSeal" (trademark hygiene). It is public but not advertised or marketed. **License note:** Engross is **AGPL-3.0** (inherited from DocuSeal — cannot be relicensed), unlike the Apache-2.0 bt-bridge-* repos; the CBB org therefore holds both permissive and copyleft public repos.

**Engross is 100% tracked in Jira (project `SIGN`) — NOT through the public repo. No external support.** When the `engross` repo is created, apply the repo-posture directives in **SPEC §1.3.1**: disable GitHub Issues/Discussions/Wiki, do not accept external pull requests, set the source-available description, and commit the **canonical `README.md`** (verbatim from SPEC §1.3.1) stating that issues/PRs are not monitored or accepted, no support/warranty is provided, all development is tracked internally, and Engross is not affiliated with or endorsed by DocuSeal. The README + disabled contribution channels exist so the public repo (a §13 compliance publication) never sets external expectations CBB will not meet.

### 3.1 Monorepo Layout (`cbb-sign`)

```
cbb-sign/
├── api/                  ← FastAPI backend
│   ├── app/
│   │   ├── routers/
│   │   ├── models/
│   │   ├── services/
│   │   └── main.py
│   ├── tests/
│   ├── alembic/
│   ├── Dockerfile
│   └── pyproject.toml
├── ui/                   ← Next.js frontend
│   ├── src/
│   ├── Dockerfile
│   └── package.json
├── CHANGELOG.md
└── README.md
```

---

## 4. Branching Strategy

Follows CBB_SDLC.md §6 (trunk-based, `main` + `dev-<version>` + issue branches).

### 4.1 Active Branch

Current active version branch: `dev-0.1.0`

### 4.2 cbb-sign Version Numbering Ladder

| Version range | Stage |
|---|---|
| `0.1.0-alpha.N` | Internal scaffolding and API skeleton |
| `0.1.0-beta.N` | Feature-complete, internal testing |
| `0.1.0-rc.N` | Release candidate — full E2E testing |
| `0.1.0` | First internal production release |
| `0.x.0` | Feature releases |
| `1.0.0` | Stable — all planned v1 features shipped, security review complete |

`prod` in resource names ≠ production. Everything is pre-prod until `1.0.0`.

### 4.3 DocuSeal Fork Versioning

The DocuSeal fork is versioned independently using a `cbb-` prefix over the upstream version: `cbb-<upstream-version>-<patch>`. Example: `cbb-1.7.2-0`. Upstream pulls are documented in the CHANGELOG.

---

## 5. Requirements Management — SPEC

The authoritative product spec for cbb-sign lives at:

```
OneDrive/CBB_Sign/04_-_Highly_Confidential/SPEC/
```

SPEC files are **never committed to any repository**. They are OneDrive-only, classification `04_-_Highly_Confidential`.

| File | Purpose |
|---|---|
| `SPEC.md` | Master spec — product overview, user roles, functional requirements |
| `SPEC_api.md` | API contract: endpoints, request/response schemas, auth flows |
| `SPEC_workflow.md` | Signing workflow: one-off, template, multi-signer, wet signature, post-sign |
| `SPEC_audit.md` | Audit trail spec: DB schema, WORM storage, immutability requirements |

---

## 6. Testing Strategy

Extends CBB_SDLC.md §9.

| Layer | Framework | Coverage target |
|---|---|---|
| Unit (API) | pytest | 80% line coverage on business logic |
| Unit (UI) | Vitest | Core components and hooks |
| Integration (API) | pytest + real Postgres (test DB) | All endpoints, auth flows, webhook handler |
| E2E | Playwright | Template send flow, one-off flow, post-sign OneDrive delivery |

**No mocking the database in integration tests** — use a real test PostgreSQL instance.

---

## 7. Release Process

### 7.1 Release Checklist

- [ ] All issues in milestone have `fixVersion` set
- [ ] All Bug issues have `affectedVersion` set
- [ ] `CHANGELOG.md` `[Unreleased]` → `[version]` renamed
- [ ] All SPEC, SDLC, runbook DRAFTs reviewed and approved or carried forward
- [ ] Dependency audit — no new high-severity CVEs
- [ ] Security review complete (required before `1.0.0`)
- [ ] Docker images built and pushed to ACR: `crcbbprod.azurecr.io/cbb-sign-api:<version>`, `crcbbprod.azurecr.io/cbb-sign-ui:<version>`
- [ ] Terraform applied — Container App revisions updated
- [ ] E2E test suite passed against staging
- [ ] GitHub Release created with CHANGELOG section + image tags

### 7.2 Deployment

All cbb-sign services deploy to `cae-cbb-prod` (Azure Container Apps environment). See `CBB_Corporate/03_-_Confidential/Infrastructure/CBB_Sign/` for architecture reference and runbook.

---

## 8. Infrastructure

Managed in `cbb-infra/services/cbb/`. See `CBB_Corporate/03_-_Confidential/Infrastructure/CBB_Sign/` for the full infrastructure doc set.

Key resources:

| Resource | Name |
|---|---|
| API Container App | `ca-cbb-sign-api-prod` |
| UI Container App | `ca-cbb-sign-ui-prod` |
| Custom domain (UI) | `sign.coldboreballisticsllc.com` |
| Custom domain (API) | `sign-api.coldboreballisticsllc.com` |
| Database | `cbb_sign` on shared PostgreSQL server (Azure VNet) |
| Audit cert storage | Azure Blob container (WORM, immutability policy) |
| Entra app registration | `app-cbb-sign` (single purpose, minimum scopes) |

---

## 9. Tools Reference

Extends CBB_SDLC.md §15.2.

| Tool | Purpose |
|---|---|
| FastAPI | API framework |
| Next.js | Web UI framework |
| SQLAlchemy + Alembic | ORM and DB migrations |
| MSAL | Entra ID authentication |
| DocuSeal OSS (private fork) | Signing engine |
| Gotenberg | `.docx` → PDF conversion |
| Microsoft Graph API | OneDrive file delivery |
| Azure Blob (WORM) | Immutable audit certificate storage |
| PostgreSQL | Audit event store (`cbb_sign` database) |

---

## Document Control

| Field | Value |
|---|---|
| **Document owner** | `jschwefel@coldboreballisticsllc.com` |
| **Classification** | Confidential (03_-_Confidential/) |
| **Location** | `OneDrive/CBB_Sign/03_-_Confidential/CBB_Sign_SDLC.md` |
| **Cross-references** | `CBB_SDLC.md`; `CBB_Sign_LOE.md`; `ONEDRIVE_ORGANIZATION_GUIDE.md` |
| **Created** | 2026-06-12 |

---

## Revision Control Block

| Rev | Date | Changed By | Reviewed By | Approved By | Summary |
|-----|------|------------|-------------|-------------|---------|
| DRAFT | 2026-06-12 | Claude Code | — | — | Initial creation — cbb-sign project SDLC |
| DRAFT | 2026-06-12 | Claude Code (Opus 4.8) | — | — | §3 repo structure corrected: the DocuSeal fork is **public, on a non-CBB account/org (NOT `ColdBoreBallistics`), and renamed** to a CBB-neutral name — AGPL-3.0 §13 satisfied by openly offering the modified source (SPEC §1.3). Fork name is an open item. cbb-sign monorepo remains private in `ColdBoreBallistics`. |
| DRAFT | 2026-06-12 | Claude Code (Opus 4.8) | — | — | OI-A resolved: the fork is named **Engross** (repo/image `engross`; collision-checked — no same-category software conflict; common-word trademark caveat noted in SPEC §1.3). §3 table + §2.3 image path updated. |
