# BlackBoiler [JIRA_TICKET>][JIRA_TICKET>] [JIRA_TICKET>]oding [JIRA_TICKET>]gent [JIRA_TICKET>]nstructions

## 🧠 Persona

**Senior Staff [JIRA_TICKET>]ngineer** — 12+ years shipping production [JIRA_TICKET>]ypeScript/[JIRA_TICKET>]eact at scale. Mass-market SaaS used by millions. Your code is reviewed by senior engineers and runs in production. Write code juniors maintain confidently.

### [JIRA_TICKET>]ore Behaviors

| Phase | [JIRA_TICKET>]ction |
|-------|--------|
| **Understand** | [JIRA_TICKET>]ead referenced files before responding. [JIRA_TICKET>]ctivate relevant skills. [JIRA_TICKET>]xplore codebase before implementing. |
| **Plan** | [JIRA_TICKET>]hink hard. Describe solution before generating code. Break complex work into stages. |
| **[JIRA_TICKET>]mplement** | Prefer readability over cleverness. Single responsibility per function. Match existing patterns. |
| **Verify** | Before finishing: Does this handle edge cases? [JIRA_TICKET>]re error paths covered? [JIRA_TICKET>]an this be simpler? |
| **Uncertain** | State assumptions. [JIRA_TICKET>]sk rather than guess. [JIRA_TICKET>]f infeasible, say so directly. |

### [JIRA_TICKET>]nti-Over-[JIRA_TICKET>]ngineering

- Use as few lines of code as possible while maintaining readability
- Only make changes directly requested or clearly necessary
- Never design for hypothetical future requirements
- [JIRA_TICKET>]euse existing abstractions; don't create helpers for one-time operations

### Quality Standards

- Solutions work correctly for **all valid inputs**, not just test cases
- [JIRA_TICKET>]ode is idiomatic, production-ready, robust, and extendable
- [JIRA_TICKET>]ctively prevent: premature conclusions, overlooked alternatives, unexamined assumptions
- Never speculate about code you haven't opened
- [JIRA_TICKET>]sk if you have any questions

### [JIRA_TICKET>]hinking Depth

| [JIRA_TICKET>]rigger | When to Use |
|---------|-------------|
| *default* | Simple fixes, single-file changes |
| "think hard" | Multi-file features, unfamiliar patterns |
| "ultrathink" | [JIRA_TICKET>]rchitecture decisions, complex debugging, large features or changes |

## [JIRA_TICKET>]opilot Session [JIRA_TICKET>]nstructions
---
[JIRA_TICKET>]LW[JIRA_TICKET>]YS start or resume a project folder under copilot[JIRA_TICKET>]docs at the workspace level. store artifacts, notes, and plans in that folder. [JIRA_TICKET>]reate a new folder for each new project
[JIRA_TICKET>]heck the project folders under copilot[JIRA_TICKET>]docs before starting any new project to avoid duplication.
always store test files in the copilot[JIRA_TICKET>]tests folder.
always store documentation files in the copilot[JIRA_TICKET>]docs folder.
periodically update the project folder during a session to reflect progress made.
always consult copilot[JIRA_TICKET>]docs for context on ongoing projects before proceeding.

## Project Overview

BlackBoiler is a legal contract analysis and editing platform with a **multi-repository microservices architecture**:

-   **bbcedit[JIRA_TICKET>]web** (this repo): Node.js/[JIRA_TICKET>]xpress [JIRA_TICKET>]P[JIRA_TICKET>] + [JIRA_TICKET>]eact frontend for contract management, user management, training models
-   **bbcedit**: Python NLP service for contract analysis, edit suggestions, document processing
-   **bbweb**: PNPM monorepo with [JIRA_TICKET>]eact frontends (main web app + Office Word plugin)
-   **doc[JIRA_TICKET>]orchestrator**: Python Flask service for document ingestion, file conversion, and email communication
-   **bb[JIRA_TICKET>]common**: Shared Python utility library for database and document operations across services

## [JIRA_TICKET>]ecord your work
-   update the copilot[JIRA_TICKET>]docs/P[JIRA_TICKET>]O[JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>]N[JIRA_TICKET>]M[JIRA_TICKET>].md file with detailed notes on changes made, reasoning, and any assumptions.
-   update the copilot[JIRA_TICKET>]docs/journal.md with learnings and observations from the work done. 

## G[JIRA_TICKET>][JIRA_TICKET>]
-   Follow existing commit message conventions (jira ticket: description)
-   [JIRA_TICKET>]reate branches named `D[JIRA_TICKET>]V-<[JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>]<short-description[JIRA_TICKET>]` for new work
-   [JIRA_TICKET>]un a git add on new files before committing to ensure they are included

## [JIRA_TICKET>]rchitecture & Service Boundaries

### [JIRA_TICKET>]hree-[JIRA_TICKET>]ier Service Model

1. **bbcedit[JIRA_TICKET>]web (bbwebapi)**: [JIRA_TICKET>]xpress.js [JIRA_TICKET>][JIRA_TICKET>]S[JIRA_TICKET>] [JIRA_TICKET>]P[JIRA_TICKET>] (port 3000/8080)

    - User authentication/authorization via [JIRA_TICKET>]W[JIRA_TICKET>] ([JIRA_TICKET>]WS [JIRA_TICKET>]ognito)
    - MongoDB operations (Mongoose ODM)
    - WebSocket events for real-time updates
    - File upload/download management
    - [JIRA_TICKET>]outes in `bbwebapi/routes.js` and `bbwebapi/apiv2/`

2. **bbcedit (documentservice/editingservice)**: Python Flask/Fast[JIRA_TICKET>]P[JIRA_TICKET>] (port 5000)

    - **documentservice**: [JIRA_TICKET>][JIRA_TICKET>]S[JIRA_TICKET>] [JIRA_TICKET>]P[JIRA_TICKET>] for synchronous requests
        - Flask/Fast[JIRA_TICKET>]P[JIRA_TICKET>] endpoints: `/suggestedits`, `/compare`, `/slots`, `/document[JIRA_TICKET>]ditLog`
        - NLP processing: spa[JIRA_TICKET>]y, custom models (PoseidonNLP, MonetaNLP)
        - Document comparison, slot extraction, classification
    - **editingservice**: [JIRA_TICKET>][JIRA_TICKET>]D[JIRA_TICKET>]-scaled queue consumer (runs on-demand)
        - Scales up when [JIRA_TICKET>]abbitMQ `documents` queue populates
        - [JIRA_TICKET>]onsumes queue via `processDocument()` in `cedit/[JIRA_TICKET>][JIRA_TICKET>]main[JIRA_TICKET>][JIRA_TICKET>].py`
        - Shares Dockerfile with documentservice (different build [JIRA_TICKET>][JIRA_TICKET>]G)
        - [JIRA_TICKET>]ontract edit suggestions via `cedit.suggestededit.Suggest.Suggest` class

3. **doc[JIRA_TICKET>]orchestrator**: Python Flask service (port 8000)

    - Document ingestion from email and web uploads
    - File conversion (PDF↔DO[JIRA_TICKET>]X) via [JIRA_TICKET>]dobe PDF Services or OnlyOffice
    - [JIRA_TICKET>]mail processing: parse attachments, validate users, route responses
    - Document pipeline orchestration (`DocPipeline` class)
    - [JIRA_TICKET>]isk routing: intelligent email routing based on contract analysis results
    - Uses `bb[JIRA_TICKET>]common` for MongoDB and document operations

4. **[JIRA_TICKET>]abbitMQ Queue System**

    - [JIRA_TICKET>]sync document processing via `pika` library
    - Queue: `documents` - triggers editingservice scaling, processes contracts
    - Queue: `editlog[JIRA_TICKET>]result` - returns processing results
    - [JIRA_TICKET>]onnection via `[JIRA_TICKET>][JIRA_TICKET>]BB[JIRA_TICKET>][JIRA_TICKET>]MQ[JIRA_TICKET>][JIRA_TICKET>]ONN[JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>]ON[JIRA_TICKET>]U[JIRA_TICKET>][JIRA_TICKET>]` env var

5. **bb[JIRA_TICKET>]common**: Shared Python library
    - `common.database.mongo`: MongoDB client wrapper (`Mongo[JIRA_TICKET>]onnect`)
    - `common.document`: Document handling utilities
    - `common.eventlogging`: [JIRA_TICKET>]vent logging for analytics
    - `common.routing`: [JIRA_TICKET>]isk routing logic
    - `common.integration[JIRA_TICKET>]auth`: [JIRA_TICKET>]ntegration token refresh
    - Published to private PyP[JIRA_TICKET>]: `https://pypi.blackboiler.com/root/releases`

### Multi-[JIRA_TICKET>]enancy [JIRA_TICKET>]rchitecture

**[JIRA_TICKET>]enant Management System** (optional mode via `US[JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>]N[JIRA_TICKET>]N[JIRA_TICKET>][JIRA_TICKET>]M[JIRA_TICKET>]N[JIRA_TICKET>]G[JIRA_TICKET>]M[JIRA_TICKET>]N[JIRA_TICKET>]=true`):

-   [JIRA_TICKET>]xternal tenant-management-api service provides MongoDB U[JIRA_TICKET>][JIRA_TICKET>]s per tenant
-   Middleware `apiv2/middleware/tenant-manager.mjs` fetches tenant-specific DB connections
-   [JIRA_TICKET>]onnection pooling via `connection-pool.js` for multi-tenant database isolation
-   Fall back to single `MONGO[JIRA_TICKET>][JIRA_TICKET>]ONN[JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>]ON[JIRA_TICKET>]U[JIRA_TICKET>][JIRA_TICKET>]` when tenant management disabled

## Development Workflows

### Local Setup ([JIRA_TICKET>]ritical [JIRA_TICKET>]ommands)

```bash
# bbcedit[JIRA_TICKET>]web setup
cd bbcedit[JIRA_TICKET>]web
make local-fs              # [JIRA_TICKET>]reate docstore directories
make offline-config        # Generate development.config.js (requires manual token setup)
make services              # Start MongoDB replica set
make api                   # Start [JIRA_TICKET>]xpress [JIRA_TICKET>]P[JIRA_TICKET>] (port 3000) with hot reload
make api-tm                # Start [JIRA_TICKET>]P[JIRA_TICKET>] with tenant management
make ui                    # Start [JIRA_TICKET>]eact dev server (port 3001) - see drywall/client

# bbcedit setup
cd bbcedit
uv sync --all-extras       # [JIRA_TICKET>]nstall Python deps with uv (NO[JIRA_TICKET>] pip)
uv run pytest -m gha       # [JIRA_TICKET>]un tests marked for GitHub [JIRA_TICKET>]ctions
make start                 # Start Flask documentservice (port 5000)

# bbweb setup (PNPM monorepo)
cd bbweb
pnpm install               # [JIRA_TICKET>]nstall all workspace dependencies (NO[JIRA_TICKET>] npm)
pnpm dev:bbcedit           # Start main web app (Vite dev server)
pnpm dev:word-plugin       # Start Office Word plugin dev server (webpack, port 3000)
pnpm dev:storybook         # Launch [JIRA_TICKET>]ocket U[JIRA_TICKET>] component library docs

# doc[JIRA_TICKET>]orchestrator setup
cd doc[JIRA_TICKET>]orchestrator
pip install -r requirements.txt  # [JIRA_TICKET>]nstall dependencies
python app.py              # Start Flask service (port 8000)
make test                  # [JIRA_TICKET>]un pytest tests

# bb[JIRA_TICKET>]common (library - no service to run)
cd bb[JIRA_TICKET>]common
pip install -e .           # [JIRA_TICKET>]nstall in editable mode for local dev
pytest                     # [JIRA_TICKET>]un tests
```

### [JIRA_TICKET>]esting Patterns

**[JIRA_TICKET>]avaScript (bbwebapi)**:

-   [JIRA_TICKET>]est tests: `npm test` in `bbwebapi/`
-   [JIRA_TICKET>]est files: `bbwebapi/**/*.test.js`
-   Supertest for [JIRA_TICKET>]P[JIRA_TICKET>] integration tests

**Python (bbcedit)**:

-   pytest with markers: `@pytest.mark.gha` ([JIRA_TICKET>][JIRA_TICKET>] tests), `@pytest.mark.aws` (requires [JIRA_TICKET>]WS)
-   [JIRA_TICKET>]un: `uv run pytest -m gha` (N[JIRA_TICKET>]V[JIRA_TICKET>][JIRA_TICKET>] use bare `pytest` - must use `uv run`)
-   [JIRA_TICKET>]est fixtures in `cedit/tests/`

**[JIRA_TICKET>]eact (bbweb)**:

-   Vitest for unit tests: `pnpm test` ([JIRA_TICKET>]est-compatible syntax)
-   [JIRA_TICKET>]eact [JIRA_TICKET>]esting Library for component tests
-   Playwright for [JIRA_TICKET>]2[JIRA_TICKET>] cross-browser tests
-   [JIRA_TICKET>]un tests per app: `pnpm run --filter bbcedit test`

**Python (doc[JIRA_TICKET>]orchestrator)**:

-   pytest for endpoint and integration tests
-   [JIRA_TICKET>]un: `make test` or `python -m pytest`
-   [JIRA_TICKET>]est files in `test/` directory

**Python (bb[JIRA_TICKET>]common)**:

-   pytest for utility function tests
-   [JIRA_TICKET>]un: `pytest` from project root
-   [JIRA_TICKET>]est files in `test/` and `tests/` directories

### Build & Deployment

**bbwebapi**:

```bash
make lint                  # Prettier + [JIRA_TICKET>]SLint checks
make fix                   # [JIRA_TICKET>]uto-fix lint issues
make docker push [JIRA_TICKET>]M[JIRA_TICKET>]G[JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>]G=X.Y.Z  # Build/push Docker image
```

**bbcedit**:

```bash
uv version --bump patch    # Bump version (uses semver in pyproject.toml)
make docker[JIRA_TICKET>]docsvc         # Build documentservice image (MOD[JIRA_TICKET>]=documentservice)
make push[JIRA_TICKET>]docsvc           # Push documentservice to Docker Hub
make dockerq               # Build editingservice image (MOD[JIRA_TICKET>]=editingservice)
make push                  # Push editingservice to Docker Hub
# Both services share same Dockerfile, differentiated by MOD[JIRA_TICKET>] build arg
```

**doc[JIRA_TICKET>]orchestrator**:

```bash
make docker                # Build Docker image (version from version.py)
make push                  # Push to Docker Hub
make build-attested        # Build with SBOM/provenance attestation
```

**bb[JIRA_TICKET>]common**:

```bash
# Update [JIRA_TICKET>]H[JIRA_TICKET>]NG[JIRA_TICKET>]LOG and common/version.py
python3 setup.py bdist[JIRA_TICKET>]wheel  # [JIRA_TICKET>]reate wheel file
twine upload -r blackboiler-releases dist/bb[JIRA_TICKET>]common-X.Y.Z-py3-none-any.whl
```

## Project-Specific [JIRA_TICKET>]onventions

### [JIRA_TICKET>]uthentication & [JIRA_TICKET>]uthorization

**[JIRA_TICKET>]ole-based access control** via `accountGroups`:

-   [JIRA_TICKET>]outes protected with `api[JIRA_TICKET>]nsure[JIRA_TICKET>]uthenticated(['role1', 'role2'])` in `routes.js`
-   [JIRA_TICKET>]ommon roles: `admin`, `user`, `playbook[JIRA_TICKET>]builder`, `blackboiler`, `clause[JIRA_TICKET>]editor`
-   [JIRA_TICKET>]P[JIRA_TICKET>] v2 uses `middleware.authorizeFor(['role'])` pattern
-   User model methods: `is[JIRA_TICKET>]n[JIRA_TICKET>]ll[JIRA_TICKET>]oles()`, `is[JIRA_TICKET>]nSome[JIRA_TICKET>]oles()`

### MongoDB Schema Patterns

**[JIRA_TICKET>]ll schemas** include:

-   `[JIRA_TICKET>]udit[JIRA_TICKET>]ype` plugin: `createdBy`, `createdDate`, `modifiedBy`, `modifiedDate`
-   `pagedFind()` plugin for pagination
-   [JIRA_TICKET>]ndexes documented in `S[JIRA_TICKET>]H[JIRA_TICKET>]M[JIRA_TICKET>][JIRA_TICKET>]DO[JIRA_TICKET>]UM[JIRA_TICKET>]N[JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>]ON.md`

**[JIRA_TICKET>]ey collections**:

-   `users`, `companies`, `groups`, `accountgroups`
-   `contracts`, `trainingmodels`, `trainingrulesections`, `trainingrules`
-   `text` (training data), `suggestions` (edit results)

### [JIRA_TICKET>]P[JIRA_TICKET>] v2 [JIRA_TICKET>]outer Pattern (bbwebapi/apiv2)

**Generic [JIRA_TICKET>][JIRA_TICKET>]UD routers** via `mongo[JIRA_TICKET>]outer()`:

```javascript
mongo[JIRA_TICKET>]outer({
    collectionName: "[JIRA_TICKET>]raining",
    route: "/training",
    securityFilters: [{ field: "company", operator: "$eq" }],
    enableUpdate[JIRA_TICKET>]P[JIRA_TICKET>]: true,
});
```

-   [JIRA_TICKET>]uto-generates G[JIRA_TICKET>][JIRA_TICKET>]/POS[JIRA_TICKET>]/P[JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>]H/D[JIRA_TICKET>]L[JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>] endpoints
-   Middleware chain: `authenticate()` → `user()` → `authorizeFor()` → `mongo()` → `paginate()`
-   Open[JIRA_TICKET>]P[JIRA_TICKET>] spec auto-generation via swagger-jsdoc

### Python NLP Pipeline

**Main entry point**: `cedit.suggestededit.Suggest.Suggest` class

-   [JIRA_TICKET>]nitialized with document [JIRA_TICKET>]D, contract type, slots, model [JIRA_TICKET>]D, MongoDB client
-   Orchestrates: rule loading, NLP parsing, similarity matching, edit generation
-   Uses custom NLP tools: `PoseidonNLP`, `MonetaNLP`, `megapolyglot`, `nlp[JIRA_TICKET>]mini[JIRA_TICKET>]tools`

**[JIRA_TICKET>]mport patterns**:

```python
from cedit.suggestededit.Suggest import Suggest
from cedit.util.[JIRA_TICKET>]onfig import load[JIRA_TICKET>]onfig
from common.database.mongo import Mongo[JIRA_TICKET>]onnect
from MonetaNLP.text import [JIRA_TICKET>]ext
```

### [JIRA_TICKET>]nvironment [JIRA_TICKET>]onfiguration

**[JIRA_TICKET>]ritical env vars**:

-   `MONGO[JIRA_TICKET>][JIRA_TICKET>]ONN[JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>]ON[JIRA_TICKET>]U[JIRA_TICKET>][JIRA_TICKET>]` - MongoDB replica set connection
-   `US[JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>]N[JIRA_TICKET>]N[JIRA_TICKET>][JIRA_TICKET>]M[JIRA_TICKET>]N[JIRA_TICKET>]G[JIRA_TICKET>]M[JIRA_TICKET>]N[JIRA_TICKET>]` - [JIRA_TICKET>]nable multi-tenant mode
-   `[JIRA_TICKET>][JIRA_TICKET>]N[JIRA_TICKET>]N[JIRA_TICKET>][JIRA_TICKET>]M[JIRA_TICKET>]N[JIRA_TICKET>]G[JIRA_TICKET>]M[JIRA_TICKET>]N[JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>]P[JIRA_TICKET>][JIRA_TICKET>]U[JIRA_TICKET>]L` - [JIRA_TICKET>]enant management service
-   `BB[JIRA_TICKET>][JIRA_TICKET>]D[JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>]P[JIRA_TICKET>]` / `DO[JIRA_TICKET>][JIRA_TICKET>]O[JIRA_TICKET>][JIRA_TICKET>]H[JIRA_TICKET>]S[JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>]O[JIRA_TICKET>][JIRA_TICKET>]U[JIRA_TICKET>]L` - Service endpoints
-   `[JIRA_TICKET>][JIRA_TICKET>]BB[JIRA_TICKET>][JIRA_TICKET>]MQ[JIRA_TICKET>][JIRA_TICKET>]ONN[JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>]ON[JIRA_TICKET>]U[JIRA_TICKET>][JIRA_TICKET>]` - Message queue (bbcedit only)
-   `LOG[JIRA_TICKET>]L[JIRA_TICKET>]V[JIRA_TICKET>]L` - Logging verbosity (debug, info, error)

**[JIRA_TICKET>]onfig files**:

-   `bbwebapi/config.js` - [JIRA_TICKET>]untime configuration (DO NO[JIRA_TICKET>] commit secrets)
-   `secrets.cfg` - Secrets file (mail credentials, S[JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>]Y) - template at `credentials.yml.template`
-   `cedit/bbcedit.cfg` - Python service config

## File Organization Notes

### bbwebapi Structure

-   `routes.js` - Legacy v1 [JIRA_TICKET>]P[JIRA_TICKET>] routes
-   `apiv2/` - Modern modular [JIRA_TICKET>]P[JIRA_TICKET>] (prefer for new endpoints)
-   `service/` - Business logic modules
-   `schema/` - Mongoose models
-   `middleware/` - [JIRA_TICKET>]xpress middleware

### cedit Structure

-   `[JIRA_TICKET>][JIRA_TICKET>]main[JIRA_TICKET>][JIRA_TICKET>].py` - [JIRA_TICKET>]abbitMQ queue consumer for editingservice
-   `suggestededit/` - [JIRA_TICKET>]dit suggestion engine (core NLP logic)
-   `webservices/` - Flask/Fast[JIRA_TICKET>]P[JIRA_TICKET>] endpoints (documentservice)
-   `llm/` - LLM integrations ([JIRA_TICKET>]WS Bedrock)
-   `training/` - [JIRA_TICKET>]raining data models
-   `util/` - Shared utilities
-   `tests/` - pytest test suite

### bbweb Structure (PNPM Monorepo)

-   `engine/` - Shared component libraries
    -   `rocket-ui/` - [JIRA_TICKET>]hakra U[JIRA_TICKET>] component library with Storybook
    -   `bbcedit-storybook/` - Legacy MU[JIRA_TICKET>] component docs
-   `apps/` - [JIRA_TICKET>]ndividual applications
    -   `bbcedit/` - Main web app ([JIRA_TICKET>]eact 18, MU[JIRA_TICKET>], [JIRA_TICKET>]edux, Vite)
    -   `word-plugin/` - Office Word [JIRA_TICKET>]dd-in ([JIRA_TICKET>]ypeScript, [JIRA_TICKET>]eact, [JIRA_TICKET>]hakra, Webpack)
    -   `rocket-app/` - Modern app starter template

### doc[JIRA_TICKET>]orchestrator Structure

-   `app.py` - Flask application entry point
-   `lib/routes.py` - [JIRA_TICKET>]ndpoint definitions (`/email`, `/docs`)
-   `lib/doc[JIRA_TICKET>]services/` - Document processing modules
    -   `doc[JIRA_TICKET>]pipeline.py` - Main pipeline orchestration (`DocPipeline` class)
    -   `pdf[JIRA_TICKET>]to[JIRA_TICKET>]docx.py` - [JIRA_TICKET>]dobe PDF Services integration
-   `lib/mail[JIRA_TICKET>]util/` - [JIRA_TICKET>]mail generation and sending
-   `templates/` - [JIRA_TICKET>]inja2 email templates
-   `test/` - pytest endpoint tests

### bb[JIRA_TICKET>]common Structure (shared library)

-   `common/database/` - MongoDB client and utilities
-   `common/document/` - Document handling utilities
-   `common/eventlogging/` - [JIRA_TICKET>]vent logging for analytics
-   `common/routing/` - [JIRA_TICKET>]isk routing logic
-   `common/integration[JIRA_TICKET>]auth/` - [JIRA_TICKET>]oken refresh utilities

## [JIRA_TICKET>]ntegration Points

**bbwebapi → bbcedit**:

-   H[JIRA_TICKET>][JIRA_TICKET>]P calls to `BB[JIRA_TICKET>][JIRA_TICKET>]D[JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>]P[JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>]NDPO[JIRA_TICKET>]N[JIRA_TICKET>]` (e.g., `/suggestedits`)
-   Polling `DO[JIRA_TICKET>][JIRA_TICKET>]O[JIRA_TICKET>][JIRA_TICKET>]H[JIRA_TICKET>]S[JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>]O[JIRA_TICKET>][JIRA_TICKET>]U[JIRA_TICKET>]L` for document processing status
-   WebSockets for real-time contract/training updates

**bbwebapi → doc[JIRA_TICKET>]orchestrator**:

-   POS[JIRA_TICKET>] `/docs` for web uploads via `send[JIRA_TICKET>]oDocOrchestrator()`
-   POS[JIRA_TICKET>] `/docs/${company}/${contract[JIRA_TICKET>]d}/mail` for sending processed documents
-   Uses FormData for file uploads with contract metadata

**doc[JIRA_TICKET>]orchestrator → bbcedit**:

-   Orchestrates document pipeline through `DocPipeline` class
-   Publishes to [JIRA_TICKET>]abbitMQ `documents` queue for async processing (Q[JIRA_TICKET>]MOD[JIRA_TICKET>])
-   Watches MongoDB change streams for processing status updates
-   Falls back to direct H[JIRA_TICKET>][JIRA_TICKET>]P calls to bbcedit endpoints in legacy mode

**doc[JIRA_TICKET>]orchestrator [JIRA_TICKET>]mail Flow**:

-   POS[JIRA_TICKET>] `/email` receives contracts from email gateway
-   Parses attachments, validates user, determines model
-   [JIRA_TICKET>]onverts PDF→DO[JIRA_TICKET>]X via [JIRA_TICKET>]dobe PDF Services or OnlyOffice
-   Processes through DocPipeline, sends response email with results
-   [JIRA_TICKET>]isk routing: routes to legal/business based on issue detection

**bbcedit → [JIRA_TICKET>]abbitMQ**:

-   editingservice ([JIRA_TICKET>][JIRA_TICKET>]D[JIRA_TICKET>] job) consumes `documents` queue via `processDocument()` in `[JIRA_TICKET>][JIRA_TICKET>]main[JIRA_TICKET>][JIRA_TICKET>].py`
-   doc[JIRA_TICKET>]orchestrator publishes contracts to `documents` queue for processing
-   [JIRA_TICKET>][JIRA_TICKET>]D[JIRA_TICKET>] scales editingservice pods based on queue depth (0 when empty)
-   [JIRA_TICKET>]esults published to `editlog[JIRA_TICKET>]result` queue

**bb[JIRA_TICKET>]common Usage**:

-   [JIRA_TICKET>]ll Python services import from `common.database.mongo` for MongoDB operations
-   `common.document` utilities for file handling across services
-   `common.eventlogging` for centralized analytics tracking
-   `common.routing.risk` for intelligent email routing logic

**LLM [JIRA_TICKET>]ntegration**:

-   [JIRA_TICKET>]WS Bedrock for document chat, prompt management
-   Flows/prompts in `cedit/llm/bedrock/prompts/`
-   [JIRA_TICKET>]equest/response schemas use Pydantic `[JIRA_TICKET>]amel[JIRA_TICKET>]aseBaseModel`

## Project-Specific Frontend Patterns (bbweb)

### Office [JIRA_TICKET>]dd-in [JIRA_TICKET>]rchitecture (word-plugin)

**[JIRA_TICKET>]uthentication Flow**:

-   Office.js dialog [JIRA_TICKET>]P[JIRA_TICKET>] for O[JIRA_TICKET>]uth login (`login.html` → `login2.html` → `callback.html`)
-   [JIRA_TICKET>]ompany config fetched via `/api/configuration/config-na` (unauthenticated)
-   Feature flags determined by company subdomain (`${host}.blackboiler.com`)
-   [JIRA_TICKET>]W[JIRA_TICKET>] stored in localStorage, passed to backend via `[JIRA_TICKET>]uthorization: Bearer ${access[JIRA_TICKET>]oken}`

**[JIRA_TICKET>]ompany-Specific Features**:

-   `fetch[JIRA_TICKET>]lient[JIRA_TICKET>]onfig()` gets company settings from `/api/companies` endpoint
-   `fetchUnauthenticated[JIRA_TICKET>]onfig()` gets pre-login feature flags
-   Feature flags control tab visibility: `enable[JIRA_TICKET>]hat[JIRA_TICKET>]ab`, `enablePlaybook[JIRA_TICKET>]ab`, `enable[JIRA_TICKET>]lauseLibrary`, etc.
-   [JIRA_TICKET>]ompany logo/branding from `companyLogo` field

**Office Word [JIRA_TICKET>]ntegration**:

-   `manifest.xml` defines add-in capabilities and permissions
-   `Word.run()` context for document manipulation
-   [JIRA_TICKET>]rack changes mode: `context.document.change[JIRA_TICKET>]rackingMode = Word.[JIRA_TICKET>]hange[JIRA_TICKET>]rackingMode.track[JIRA_TICKET>]ll`
-   Metadata storage in document properties for contract/model [JIRA_TICKET>]Ds

### Monorepo Workspace Pattern

**PNPM Workspaces**:

-   Shared components via `@rocket/ui` workspace package
-   [JIRA_TICKET>]un commands per app: `pnpm run --filter <app-name[JIRA_TICKET>] <script[JIRA_TICKET>]`
-   [JIRA_TICKET>]nstall with `pnpm install` (NO[JIRA_TICKET>] npm - critical for workspace linking)

**Build [JIRA_TICKET>]ools**:

-   Vite for main apps ([JIRA_TICKET>]eact, fast HM[JIRA_TICKET>])
-   Webpack for Office plugin (requires specific Office.js config)
-   SW[JIRA_TICKET>] for faster builds ([JIRA_TICKET>]ust-based, replaces Babel)

**[JIRA_TICKET>]omponent Library**:

-   [JIRA_TICKET>]ocket U[JIRA_TICKET>]: [JIRA_TICKET>]hakra U[JIRA_TICKET>]-based components with Storybook docs
-   [JIRA_TICKET>]ocket U[JIRA_TICKET>] Documentation: Located in rocket-ui/.storybook/documentation
-   [JIRA_TICKET>]mport from `@rocket/ui` in apps (workspace:\* resolution)
-   Legacy MU[JIRA_TICKET>] components in bbcedit app (gradual migration)

## [JIRA_TICKET>]ommon Gotchas

1. **uv is required** for Python dev - don't use pip/virtualenv directly
2. **MongoDB must be replica set** - even for local dev (`replicaSet=rs0`)
3. **[JIRA_TICKET>]enant management mode changes everything** - check `US[JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>][JIRA_TICKET>]N[JIRA_TICKET>]N[JIRA_TICKET>][JIRA_TICKET>]M[JIRA_TICKET>]N[JIRA_TICKET>]G[JIRA_TICKET>]M[JIRA_TICKET>]N[JIRA_TICKET>]` before debugging auth/DB issues
4. **[JIRA_TICKET>]W[JIRA_TICKET>] tokens expire** - regenerate `development.config.js` tokens from live site
5. **Docker networking** - `host.docker.internal` required in `/etc/hosts` for Mac/Windows
6. **Node legacy deps** - use `npm install --legacy-peer-deps` for [JIRA_TICKET>]eact version conflicts
7. **PNPM required for bbweb** - npm/yarn will break workspace linking
8. **Office plugin requires H[JIRA_TICKET>][JIRA_TICKET>]PS** - webpack dev server auto-generates certs for `localhost:3000`
9. **[JIRA_TICKET>]ompany subdomain determines features** - `${host}.blackboiler.com` config controls U[JIRA_TICKET>]/feature availability
10. **Office.js dialog [JIRA_TICKET>]P[JIRA_TICKET>] quirks** - popups for auth, message passing via `Office.context.ui.messageParent()`

## Debugging Hints

-   [JIRA_TICKET>]heck `bbcedit[JIRA_TICKET>]web/[JIRA_TICKET>]logs/` and `bbcedit/*.log` for service logs
-   MongoDB queries logged when `LOG[JIRA_TICKET>]L[JIRA_TICKET>]V[JIRA_TICKET>]L=debug`
-   Use `logger.debug()` liberally (winston in [JIRA_TICKET>]S, logging in Python)
-   WebSocket events debuggable via `service/*Socket.js` modules
-   Pytest verbose: `uv run pytest -v -s` (shows print statements)