Domain Model

This section defines all entities in the Courier system, their relationships, and the conventions used across the codebase. The domain model serves as the single source of truth for the data structures that underpin every subsystem.

4.1 Design Conventions

Aggregate roots are implemented as C# class types. These are mutable entities tracked by EF Core's change tracker and represent the top-level objects that own their child entities. Examples: Job, Connection, PgpKey, FileMonitor.

Value objects are implemented as C# record types. These are immutable, compared by value, and typically serialized as JSON columns or embedded within aggregate roots. Examples: StepConfiguration, FailurePolicy, TransferProgress, VerifyResult.

General conventions:

• All entities use Guid primary keys, generated application-side via Guid.NewGuid()
• All entities include CreatedAt and UpdatedAt timestamps, set automatically via EF Core interceptors
• All major entities support soft delete via an IsDeleted flag and DeletedAt timestamp. Soft-deleted entities are excluded from normal queries via a global query filter
• Nullable reference types are enabled project-wide. Non-nullable properties are required; nullable properties are optional
• Navigation properties use IReadOnlyList<T> for collections to enforce modification through aggregate root methods
• JSON columns (PostgreSQL JSONB) are used for flexible, schema-light data like step configuration and audit details

4.2 Entity Catalog

4.2.1 Job System Entities

Job (aggregate root — class)

The central entity representing a named, versioned pipeline of steps.

JobStep (entity owned by Job)

JobVersion (entity owned by Job)

JobExecution (aggregate root — class)

A single run of a job. Owns its step executions and context snapshot.

StepExecution (entity owned by JobExecution)

JobChain (aggregate root — class)

JobChainMember (entity owned by JobChain)

ChainExecution (aggregate root — class)

JobDependency (entity)

Represents a dependency edge between two standalone jobs (outside of chains).

JobSchedule (entity)

Attached to a Job via job_schedules table.

ChainSchedule (entity)

Attached to a JobChain via chain_schedules table. Mirrors JobSchedule exactly.

4.2.2 Connection Entities

Connection (aggregate root — class)

KnownHost (entity owned by Connection)

4.2.3 Key Store Entities

PgpKey (aggregate root — class)

SshKey (aggregate root — class)

4.2.4 File Monitor Entities

FileMonitor (aggregate root — class)

MonitorJobBinding (entity owned by FileMonitor)

MonitorDirectoryState (entity owned by FileMonitor)

MonitorFileLog (entity owned by FileMonitor)

4.2.5 Cross-Cutting Entities

Tag (aggregate root — class)

EntityTag (join entity)

Polymorphic association linking any taggable entity to a tag.

AuditLogEntry (entity — append-only)

Unified audit log with an entity type discriminator.

The audit log uses a single table with a JSONB Details column for flexibility. Subsystem-specific fields (bytes transferred, transfer rate, error stack traces) are stored in the Details JSON rather than as top-level columns. This avoids a wide, sparse table while keeping all audit data queryable via PostgreSQL's JSONB operators.

Indexes: (EntityType, EntityId, PerformedAt) for entity-specific history queries, (PerformedAt) for time-range queries, (PerformedBy, PerformedAt) for user activity queries.

DomainEvent (entity — append-only)

Persisted domain events for V2 notification subscribers. Separate from the audit log because events are actionable (consumed by handlers) while audit entries are historical records.

In V1, events are written but ProcessedAt remains null (no subscribers yet). This table is designed as a transactional outbox: events are written in the same database transaction as the state change that produced them, guaranteeing consistency. In V2, this outbox becomes the foundation for event-driven scheduling — a relay process reads unprocessed events (using FOR UPDATE SKIP LOCKED to prevent duplicate delivery), publishes them to a message bus (Azure Service Bus or RabbitMQ), and marks them processed. This replaces database polling for job coordination and enables at-least-once delivery, fan-out notifications, and horizontal Worker scaling (see Section 15).

SystemSetting (entity)

Key-value configuration for runtime-adjustable settings.

4.3 Value Objects

Value objects are implemented as C# record types. They are immutable, compared by value, and stored either as JSONB columns or as embedded properties within their parent entity.

public record FailurePolicy(
    FailurePolicyType Type,       // Stop, RetryStep, RetryJob, SkipAndContinue
    int MaxRetries = 3,
    int BackoffBaseSeconds = 1,
    int BackoffMaxSeconds = 60);

public record StepConfiguration(
    Dictionary<string, object> Parameters);  // Flexible key-value config per step type

public record WatchTarget(
    WatchTargetType Type,         // Local, Remote
    string Path,                  // Directory path
    Guid? ConnectionId);          // FK to Connection (null for local)

public record SshAlgorithmConfig(
    List<string>? KeyExchange,
    List<string>? Encryption,
    List<string>? Mac,
    List<string>? HostKey);

public record SplitArchiveConfig(
    bool Enabled,
    int MaxPartSizeMb = 500);

4.4 Enumerations

// Job System
public enum JobExecutionState { Created, Queued, Running, Paused, Completed, Failed, Cancelled }
public enum StepExecutionState { Pending, Running, Completed, Failed, Skipped }
public enum ChainExecutionState { Pending, Running, Completed, Failed, Paused, Cancelled }
public enum FailurePolicyType { Stop, RetryStep, RetryJob, SkipAndContinue }
public enum ScheduleType { Cron, OneShot }

// Connections
public enum ConnectionProtocol { SFTP, FTP, FTPS }
public enum AuthMethod { Password, SshKey, PasswordAndSshKey }
public enum HostKeyPolicy { TrustOnFirstUse, AlwaysTrust, Manual }
public enum TlsCertPolicy { SystemTrust, PinnedThumbprint, Insecure }
public enum ConnectionStatus { Active, Disabled }
public enum TlsVersion { TLS_1_0, TLS_1_1, TLS_1_2, TLS_1_3 }

// Keys
public enum PgpAlgorithm { RSA_2048, RSA_3072, RSA_4096, ECC_CURVE25519, ECC_P256, ECC_P384 }
public enum PgpKeyType { PublicOnly, KeyPair }
public enum PgpKeyStatus { Active, Expiring, Retired, Revoked, Deleted }
public enum SshKeyType { RSA_2048, RSA_4096, ED25519, ECDSA_256 }
public enum SshKeyStatus { Active, Retired, Deleted }

// File Monitor
public enum MonitorState { Active, Paused, Disabled, Error }
public enum WatchTargetType { Local, Remote }

[Flags]
public enum TriggerEventFlags
{
    FileCreated = 1,
    FileModified = 2,
    FileExists = 4
}

// Cross-cutting
public enum TaggableEntityType { Job, JobChain, Connection, PgpKey, SshKey, FileMonitor }
public enum AuditableEntityType { Job, JobExecution, StepExecution, Chain, ChainExecution, Connection, PgpKey, SshKey, FileMonitor }

4.5 Entity Relationship Diagram

┌──────────────────────────────────────────────────────────────────────────────────┐
│                              JOB SYSTEM                                          │
│                                                                                  │
│  ┌─────────┐ 1    * ┌──────────┐         ┌──────────────┐                       │
│  │   Job   │───────│ JobStep  │         │ JobSchedule  │                       │
│  └────┬────┘        └──────────┘         └──────────────┘                       │
│       │ 1                                  1 *                                   │
│       ├──────────* ┌──────────────┐                                              │
│       │            │  JobVersion  │         ┌────────────┐  1  * ┌──────────────┐│
│       │            └──────────────┘         │ JobChain   │─────│ChainSchedule ││
│       │ 1                                    └────┬────┘       └──────────────┘│
│       ├──────────* ┌──────────────┐               │ 1                            │
│       │            │ JobExecution │◄──────────┐   ├──────* ┌────────────────┐    │
│       │            └──────┬───────┘           │   │        │ JobChainMember │    │
│       │                   │ 1                  │   │        └────────────────┘    │
│       │                   ├────* ┌─────────────┤   │ 1                            │
│       │                   │     │StepExecution ││   ├──────* ┌────────────────┐    │
│       │                   │     └──────────────┘│   │        │ChainExecution │    │
│       │                   │                      │   │        └────────────────┘    │
│       │ *                 └──────────────────────┘   │                              │
│       ├────────────── ┌────────────────┐              │                             │
│       │               │ JobDependency  │              │                             │
│       │               │ (upstream/     │              │                             │
│       │               │  downstream)   │              │                             │
│       │               └────────────────┘              │                             │
│       │                                               │                             │
│  ─ ─ ─│─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─  │
│       │              CONNECTIONS                      │                             │
│       │                                               │                             │
│       │         ┌────────────┐ 1    * ┌───────────┐  │                             │
│       │         │ Connection │───────│ KnownHost │  │                             │
│       │         └──────┬─────┘        └───────────┘  │                             │
│       │                │                              │                             │
│       │                │ *..1                          │                             │
│       │                ▼                               │                             │
│       │         ┌────────────┐                        │                             │
│       │         │   SshKey   │                        │                             │
│       │         └────────────┘                        │                             │
│       │                                               │                             │
│  ─ ─ ─│─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─  │
│       │              KEY STORE                        │                             │
│       │                                               │                             │
│       │         ┌────────────┐                        │                             │
│       │         │   PgpKey   │                        │                             │
│       │         │            │───── successor_key_id  │                             │
│       │         └────────────┘      (self-ref)        │                             │
│       │                                               │                             │
│  ─ ─ ─│─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─│─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─  │
│       │            FILE MONITORS                      │                             │
│       │                                               │                             │
│       │  ┌─────────────┐ 1  * ┌────────────────────┐ │                             │
│       ├─│ FileMonitor  │────│ MonitorJobBinding   │─┘                             │
│       │  └──────┬──────┘     └────────────────────┘                               │
│       │         │ 1                                                                │
│       │         ├──────* ┌───────────────────────┐                                │
│       │         │        │ MonitorDirectoryState  │                                │
│       │         │        └───────────────────────┘                                │
│       │         │ 1                                                                │
│       │         └──────* ┌──────────────────┐                                     │
│       │                  │  MonitorFileLog   │                                     │
│       │                  └──────────────────┘                                     │
│       │                                                                            │
│  ─ ─ ─│─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ │
│       │              CROSS-CUTTING                                                 │
│       │                                                                            │
│       │  ┌─────────┐ *    * ┌───────────┐                                         │
│       └─│   Tag    │◄─────│ EntityTag  │──── polymorphic FK to any taggable entity│
│          └─────────┘        └───────────┘                                         │
│                                                                                    │
│          ┌────────────────┐     ┌──────────────┐     ┌───────────────┐            │
│          │ AuditLogEntry  │     │ DomainEvent  │     │ SystemSetting │            │
│          │ (unified,      │     │ (actionable, │     │ (key-value    │            │
│          │  append-only)  │     │  append-only) │     │  config)      │            │
│          └────────────────┘     └──────────────┘     └───────────────┘            │
│                                                                                    │
└──────────────────────────────────────────────────────────────────────────────────┘

KEY RELATIONSHIPS:
  Job ──1:*──► JobStep             Job owns its ordered steps
  Job ──1:*──► JobVersion          Job owns its version history
  Job ──1:*──► JobExecution        Job owns its execution history
  Job ──1:*──► JobSchedule         Job can have multiple schedules
  Job ──*:*──► Job                 Via JobDependency (upstream/downstream)
  JobExecution ──1:*──► StepExecution    Execution owns step executions
  JobChain ──1:*──► JobChainMember      Chain owns ordered member references
  JobChain ──1:*──► ChainExecution      Chain owns chain execution history
  JobChain ──1:*──► ChainSchedule       Chain can have multiple schedules
  ChainExecution ──1:*──► JobExecution   Chain execution owns job executions
  Connection ──1:*──► KnownHost         Connection owns host fingerprints
  Connection ──*:1──► SshKey            Connections reference SSH keys
  FileMonitor ──1:*──► MonitorJobBinding    Monitor binds to jobs/chains
  FileMonitor ──1:*──► MonitorDirectoryState Monitor owns directory snapshots
  FileMonitor ──1:*──► MonitorFileLog       Monitor owns dedup log
  MonitorJobBinding ──*:1──► Job/JobChain   Binding references a job or chain
  PgpKey ──0:1──► PgpKey            Successor key (self-referencing)
  Tag ──*:*──► (any taggable)       Via EntityTag polymorphic join

---