Copy page

Microservices

Glossary

Glossary

Relevant source files

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

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

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.

Code
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.

Code
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