# Glossary

# Glossary

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [.devin/rules/code-guardrails.md](.devin/rules/code-guardrails.md)
- [.devin/rules/data-model-conventions.md](.devin/rules/data-model-conventions.md)
- [.devin/rules/dev-server.md](.devin/rules/dev-server.md)
- [.devin/rules/workflow.md](.devin/rules/workflow.md)
- [AGENTS.md](AGENTS.md)
- [docs/gitflow.md](docs/gitflow.md)
- [emailsender/src/db/schema-snapshot.ts](emailsender/src/db/schema-snapshot.ts)
- [emailsender/src/domain/entities/entity-decorators.ts](emailsender/src/domain/entities/entity-decorators.ts)
- [emailsender/src/nats/types.ts](emailsender/src/nats/types.ts)
- [emailsender/src/providers/brevo.ts](emailsender/src/providers/brevo.ts)

</details>



This page provides definitions for codebase-specific terminology, architectural patterns, and domain concepts used within the Primebrick v3 Microservices repository. It serves as a reference for onboarding engineers to understand the specific vocabulary used in code and documentation.

## Architectural & Process Terms

### Tic-Toc Planning
A mandatory workflow cycle for AI agents (and recommended for humans) to ensure architectural alignment before code is modified. It consists of an **Analysis Phase**, the creation of an `ai-plans/` markdown file, and a **MANDATORY BLOCKER** where the agent halts until the user provides the "PROCEED" keyword.
*   **Implementation**: Defined in the governance rules at [.devin/rules/workflow.md:4-17]().
*   **Data Flow**: 
    1. Analysis (No code changes).
    2. Plan generation in `primebrick-workspace/ai-plans/`.
    3. User Review.
    4. Execution.

### Snake_case Enforcement
A "Golden Rule" across the repository requiring that all database columns, TypeScript interfaces, and JSON payloads (Request/Response) use `snake_case`. This eliminates the need for field renaming (DTO transformation) between layers.
*   **Implementation**: Governed by [.devin/rules/data-model-conventions.md:12-16]().
*   **Exceptions**: Only permitted at External API adapter boundaries (e.g., [emailsender/src/providers/brevo.ts:1-11]()) where the third-party service dictates the naming convention.

### GitFlow
The branching model used for version control. It strictly separates `develop` (integration), `main` (production), `feature/` (new work), `release/` (version preparation), and `hotfix/` (production patches).
*   **Implementation**: Detailed in [docs/gitflow.md:1-21]().
*   **Key Rule**: Manual versioning in `package.json` is required as there is no automated sync script [docs/gitflow.md:46-51]().

---

## Data Layer Concepts

### Entity Metadata (Decorators)
A system using TypeScript decorators to map classes to database tables without a heavy ORM. It uses a `WeakMap` named `META` to store configuration about tables, keys, and columns.
*   **Key Decorators**:
    *   `@Entity()`: Maps a class to a table name [emailsender/src/domain/entities/entity-decorators.ts:158-164]().
    *   `@Key()`: Defines the Primary Key [emailsender/src/domain/entities/entity-decorators.ts:19]().
    *   `@Column()`: Overrides default SQL mappings [emailsender/src/domain/entities/entity-decorators.ts:189-191]().
*   **Source**: [emailsender/src/domain/entities/entity-decorators.ts:9-108]().

### Schema Snapshot
A JSON representation of the "intended" database state (derived from `@Entity` metadata) or the "actual" state (introspected from PostgreSQL). The system compares these snapshots to generate migration patches.
*   **Key Function**: `compareSnapshots(entitySnap, dbSnap)` [emailsender/src/db/schema-snapshot.ts:62-161]().
*   **Heuristics**: Includes `findLikelyRenames` to suggest `ALTER TABLE ... RENAME COLUMN` instead of drop/create [emailsender/src/db/schema-snapshot.ts:7-11]().

**Diagram: Data Model to Code Entity Mapping**
This diagram illustrates how the `Entity` decorator metadata is processed into a `SchemaSnapshot` for comparison.

```mermaid
graph TD
    subgraph "Natural Language Space"
        A["User defines a Table"]
        B["User defines a Column"]
    end

    subgraph "Code Entity Space"
        C["@Entity('table_name')"]
        D["@Column({ pgType: 'varchar' })"]
        E["META (WeakMap)"]
        F["syncImplicitEntityColumns()"]
        G["SchemaSnapshot Object"]
    end

    A --> C
    B --> D
    C --> E
    D --> E
    E --> F
    F --> G
```
Sources: [emailsender/src/domain/entities/entity-decorators.ts:99-152](), [emailsender/src/db/schema-snapshot.ts:17-18]().

---

## Email Domain Concepts

### Brevo Provider
The primary external service for dispatching emails. The integration is handled by the `BrevoClient` which maps internal requests to the Brevo API format.
*   **Implementation**: [emailsender/src/providers/brevo.ts:23-60]().
*   **Status Mapping**: The `mapStatus` function converts Brevo-specific event strings (e.g., "hardbounce") into internal system statuses (e.g., "bounced") [emailsender/src/providers/brevo.ts:62-79]().

### Messaging Contracts (NATS)
The definitions for inter-service communication via NATS JetStream.
*   **SendEmailRequest**: The payload required to trigger an email dispatch, including `templateCode` and `variables` [emailsender/src/nats/types.ts:1-12]().
*   **SendEmailResponse**: The acknowledgement containing the `providerMessageId` or an error string [emailsender/src/nats/types.ts:14-20]().

**Diagram: Email Dispatch Request Flow**
Mapping the NATS message interface to the Brevo Provider execution.

```mermaid
sequenceDiagram
    participant N as "NATS JetStream"
    participant S as "EmailSender Service"
    participant B as "BrevoClient"

    Note over N, B: Inter-service Communication
    N->>S: SendEmailRequest (requestId, templateCode)
    Note right of S: src/nats/types.ts:1-12
    
    S->>S: Render Template (Handlebars)
    
    S->>B: sendEmail(BrevoEmailRequest)
    Note right of B: src/providers/brevo.ts:32-60
    
    B-->>S: BrevoEmailResponse (messageId)
    S-->>N: SendEmailResponse (success: true)
    Note right of N: src/nats/types.ts:14-20
```
Sources: [emailsender/src/nats/types.ts:1-20](), [emailsender/src/providers/brevo.ts:32-60]().

---

## Infrastructure Terms

### Dev Server Management
Specific rules for managing Node.js processes on Windows development machines to prevent port conflicts.
*   **Tooling**: Uses `netstat -ano` and `Get-CimInstance Win32_Process` to identify existing PIDs before starting new services [.devin/rules/dev-server.md:23-27]().
*   **Policy**: Agents must never kill a PID holding a port without explicit instruction [.devin/rules/dev-server.md:44-46]().

### Code Guardrails
Constraints placed on AI agents to prevent infinite loops or architectural drift.
*   **Max Retry**: 2 attempts to fix linting/compilation errors before entering a **BLOCKED** state [.devin/rules/code-guardrails.md:7-10]().
*   **Scope Locking**: Prohibition against altering function signatures or shared state unless specified in an approved plan [.devin/rules/code-guardrails.md:13-14]().

---
**Sources:**
- [docs/gitflow.md:1-108]()
- [.devin/rules/workflow.md:1-17]()
- [.devin/rules/data-model-conventions.md:1-47]()
- [.devin/rules/dev-server.md:1-49]()
- [AGENTS.md:1-31]()
- [.devin/rules/code-guardrails.md:1-15]()
- [emailsender/src/db/schema-snapshot.ts:1-161]()
- [emailsender/src/domain/entities/entity-decorators.ts:1-191]()
- [emailsender/src/nats/types.ts:1-28]()
- [emailsender/src/providers/brevo.ts:1-81]()