02 — Backend Modules

For each module: entities (with field summary), command/query handlers (with file path), validators, business rules, lifecycle diagrams, and notification events emitted. Endpoint URLs are catalogued in 07-api-reference; column-level types in 03-database.

Format: every command/query references its handler at src/AssetTracking.Application/Features/<Module>/<Feature>/<Name>.cs. Entity FKs reference the entities defined in this doc.

Index

1. Identity & Access
2. Master Data
3. Assets
4. Audits
5. Transfers
6. Custody
7. Maintenance
8. Notifications
9. Documents
10. Reporting
11. Settings
12. System

Identity & Access

Auth, users, roles, permissions, sessions, login audit. The cornerstone module — every other module's permission gates resolve through it.

Entities

Auth flow

sequenceDiagram
  participant C as Client
  participant API
  participant TS as JwtTokenService
  participant PR as PermissionResolver

  C->>API: POST /api/v1/auth/login {email, password}
  API->>API: LoginCommandHandler — verify + check IsActive + lockout
  API->>TS: GenerateTokensAsync(user)
  TS->>PR: GetEffectivePermissionsAsync
  TS->>API: { accessToken, refreshToken, expirations }
  API->>C: 200 + tokens + LoginAudit row written

  C->>API: GET /api/v1/* with Authorization: Bearer <jwt>
  API->>API: UseAuthentication → JwtBearer validates signature
  API->>API: RequirePermissionFilter → PR.GetEffectivePermissionsAsync (cached)

  Note over C: 15 min later, access token expires
  C->>API: POST /auth/refresh {refreshToken}
  API->>TS: RefreshAsync(token)
  TS->>TS: Validate hash, family, not-revoked, not-expired
  TS->>TS: ROTATE — old.ReplacedByTokenHash = hash(new); old.RevokedAt = now
  TS->>API: { newAccessToken, newRefreshToken }
  TS-->>API: REUSE DETECTED — revoke whole family, throw 422

  C->>API: POST /auth/logout
  API->>API: LogoutCommandHandler — revoke specific refresh token

Auth handlers (Application/Features/Auth/)

LoginCommandHandler writes a LoginAudit row on every attempt regardless of outcome. AccessFailedCount increments on InvalidPassword; lockout is set when count exceeds the configured threshold (currently hardcoded — see handler).

User handlers (Application/Features/Users/)

Role handlers (Application/Features/Roles/)

Permission handlers (Application/Features/Permissions/)

Permissions are catalog-only; CRUD is closed (only the seeder writes). Obsolete keys are hard-deleted via DatabaseSeeder.obsoleteKeys.

User-Role assignment (Application/Features/UserRoles/)

Both invalidate the affected user's permission cache.

User-Permission overrides (Application/Features/UserPermissions/)

Login audit (Application/Features/LoginAudits/)

Master Data

Hierarchical or flat catalog tables that other entities reference dimensionally.

Hierarchical entities — Organization, Location, Classification

All three follow the same pattern: self-referencing parent FK, Level field (root=1), bilingual name+description, optional image. Shared traits:

Hierarchy depth + labels

Configurable per HierarchyEntityType (Location/Organization/Classification) via the HierarchyConfig + HierarchyLevel settings tables. See §Settings. The HierarchyConfig row caps the maximum depth (e.g., 5 levels for Location) and provides per-level labels (e.g., level 2 = "Floor").

Code generation for hierarchical entities

IHierarchicalCodeService (Persistence) builds child codes by concatenating parent + per-level digits:

Org root:  ORG-000001
Org L2:    ORG-000001-DEPT-0001

Padding width per level comes from HierarchyLevel.CodeDigits.

Operations (parallel for all three)

Endpoints follow the same shape — substitute Organizations / Locations / Classifications:

Flat entities — Vendor, Manufacturer

No hierarchy. Bilingual name + contact info.

Operations: Get*s, Get*ById, Create*, Update*, Delete*, Export*, Import* — same pattern, all under Application/Features/Vendors/ and Application/Features/Manufacturers/.

Assets

The hub of the system. Every other operational entity references Asset.

Entities

Asset field detail

AssetDetails field detail

SerialNumber (often required by classification), ManufacturerId?, VendorId?, Model, Inches, Color, Weight, Price, CurrencyCode, PurchaseDate, PurchaseOrderNumber, WarrantyStart, WarrantyEnd, ExpectedUsefulLifeMonths, CustomFieldsJson (free-form JSON for per-classification extras).

AssetStatus field detail

Key (stable string code, e.g. "Active"), NamePrimary/Secondary, Color (hex), SortOrder, IsTerminal (e.g. Disposed is terminal — no further changes allowed).

Seeded statuses (DatabaseSeeder._assetStatuses):

AssetStatusHistory (representative — same shape for the other 3 history tables)

Asset handlers (Application/Features/Assets/)

History row creation

Every UpdateAsset-style handler that mutates StatusId/LocationId/OrganizationId/CurrentCustodianId creates a corresponding history row in the same transaction. Source reflects the trigger (Manual for direct edits, Audit for review write-back, etc.), and SourceRefId carries the originating entity's id so the history page can deep-link back.

Audits

The most complex module. Lifecycle: Plan → Scope resolve → Assignment → Mobile execution → Submission → Review → Write-back → Plan roll-up.

Entities

AuditPlan field detail

NamePrimary/Secondary, DescriptionPrimary/Secondary, Status (Draft/Scheduled/InProgress/Completed/Cancelled), Priority (Low/Normal/High/Urgent), ResolvedAssetCount (cached, populated on create from IAuditScopeResolver).

Removed fields: StartDate, EndDate. The product decided plans don't need start/end dates separately from scheduling state. (Squashed into the consolidated InitialCreate migration on 2026-05-04.)

AuditPlanScope shapes

ScopeType enum dictates which fields are used:

Resolver: Application/Services/AuditScopeResolver.cs (IAuditScopeResolver). Used by CreateAuditPlanCommandHandler (compute resolved count) and CreateAssignmentCommandHandler (build the asset list for snapshotting).

AuditAssignment field detail

Invariant: only one active (non-cancelled) assignment per plan. CreateAssignmentCommandHandler:51 enforces with a ConflictException. To re-assign, cancel the existing one first.

Removed: DueDate. (Squashed into the consolidated InitialCreate migration on 2026-05-04.)

AuditAssignmentAsset — snapshots

Captured at assignment-create time so discrepancy detection is stable even if the asset's actual fields change before submission:

ExpectedOrganizationId   ExpectedLocationId   ExpectedClassificationId   ExpectedStatusId   ExpectedCustodianId?

These are what the mobile app shows the auditor as "should be here". Comparing the auditor's observed values to these produces the Outcome.

AuditResult + AuditResultLine field detail

AuditResult: AuditAssignmentId, SubmittedBy, SubmittedAt, ClientSubmissionId (idempotency key from mobile), DeviceInfo, Latitude/Longitude (optional GPS), ReviewStatus (PendingReview→InReview→Approved/Rejected (terminal)/UnderClarification), ReviewStartedAt, ReviewCompletedAt, ReviewedBy.

AuditResultLine: AuditResultId, AssetId? (null for purely-extra lines that didn't resolve), Outcome, IdentificationMethod (Qr/Manual), Observed*Id fields, ObservedConditionRating?, Notes, PhotosCount. Linked photos live in DocumentLink rows with OwnerType=AuditResultLine.

AuditOutcome enum

Classification is intentionally not an outcome — assets' codes are derived from classification, so a mis-classified asset must be deleted and re-imported. See AuditOutcome.cs doc comment.

AuditReviewAction

AuditResultLineId, Action (Approve/Reject/Modify), reviewer-modified ModifiedOrganizationId/LocationId/ClassificationId (only used when Action=Modify), Notes, ActedAt, ActedBy.

A line can have multiple review actions over time (e.g., line was rejected, auditor clarifies, reviewer approves). The latest action wins for write-back.

Audit lifecycle

stateDiagram-v2
  [*] --> Draft : CreateAuditPlan
  Draft --> Scheduled : CreateAssignment (first)
  Scheduled --> InProgress : SubmitResult (first)
  InProgress --> Completed : ReviewLines (last assignment fully approved)
  Draft --> Cancelled
  Scheduled --> Cancelled
  InProgress --> Cancelled

  state Assignment {
    [*] --> Assigned : CreateAssignment
    Assigned --> Downloaded : mobile downloads template / draft
    Downloaded --> InProgress : SaveDraft
    InProgress --> Submitted : SubmitResult
    Submitted --> InReview : reviewer opens it
    InReview --> Completed : all lines reviewed
    Assigned --> Cancelled
    Downloaded --> Cancelled
    InProgress --> Cancelled
  }

Audit Plan handlers (Application/Features/AuditPlans/)

Audit Assignment handlers (Application/Features/AuditAssignments/)

Audit Result handlers (Application/Features/AuditResults/)

Notification events emitted

Transfers

Asset transfer workflow with multi-line approval gating.

Entities

AssetTransfer:

AssetTransferLine: AssetTransferId, AssetId, ReceivedAt?, ReceivedStatus? (Ok/Damaged/Missing), Notes?.

Lifecycle

stateDiagram-v2
  [*] --> Draft : CreateTransfer
  Draft --> Submitted : SubmitTransfer
  Submitted --> Approved : ApproveTransfer
  Approved --> InTransit : (auto on Approve, in handler)
  InTransit --> Completed : CompleteTransfer (after all lines received)
  Submitted --> Rejected : RejectTransfer
  Draft --> Cancelled : CancelTransfer
  Submitted --> Cancelled : CancelTransfer

ApproveTransferCommandHandler sets status to Approved and immediately to InTransit in the same save (implementation detail — the Approved state is barely visible; you can think of it as a single action).

Operations (Application/Features/AssetTransfers/)

CompleteTransferCommandHandler:

1. Refuses if any line has no ReceivedAt.
2. For each line with ReceivedStatus = Ok: writes the new location/org to the asset and creates AssetLocationHistory / AssetOrganizationHistory rows with Source = Transfer, SourceRefId = transferId.

Notifications emitted

Custody

Per-asset check-out / check-in tracking. Independent of transfers (which move an asset's home location).

CheckOut entity

Operations (Application/Features/CheckOuts/)

Overdue status is computed by a periodic job (or filtered ad-hoc on read) based on ExpectedReturnAt < now. Not persisted automatically.

Maintenance

Three layers: MaintenancePlan (scheduled, reusable) → MaintenanceRequest (user-filed) → WorkOrder (the actual work).

MaintenancePlan + MaintenancePlanAsset

Multi-asset plans. The single-AssetId and ClassificationId fields that earlier shipped on MaintenancePlan were dropped in favor of a many-to-many join table.

MaintenancePlan fields: NamePrimary/Secondary, Frequency (Daily/Weekly/Monthly/Quarterly/Yearly/CustomDays), CustomIntervalDays?, NextDueDate?, LastPerformedDate?, EstimatedDurationHours?, DefaultVendorId?, IsActive.

MaintenancePlanAsset: MaintenancePlanId, AssetId. Unique on (PlanId, AssetId).

MaintenanceRequest

User-filed report. Fields:

WorkOrder

The unit of work — assigned to a user or vendor, scheduled, costed.

Operations

MaintenancePlans (Application/Features/MaintenancePlans/)

MaintenanceRequests (Application/Features/MaintenanceRequests/)

WorkOrders (Application/Features/WorkOrders/)

work-order.update ("Update Work Orders") gates Start + Cancel. work-order.close ("Close Work Orders") gates Complete only. Both controller endpoints are wired and the frontend gates the matching buttons. (See §Frontend §work-order-detail.)

Notifications emitted

Notifications

Bilingual template engine + per-user preferences + in-app + email channels.

Entities

NotificationTemplate field detail

Key (event id, e.g. audit.assigned), Channel (InApp/Email), SubjectPrimary?/Secondary? (subject in two languages), BodyPrimary/Secondary? (body in two languages), IsActive. Same key can have one row per channel.

Notification field detail

RecipientUserId, Title, Body (rendered + plain-text-cleaned for InApp — <p> and   stripped), Severity (Info/Success/Warning/Error), Link? (relative path), IsRead, ReadAt?, TemplateKey, ContextJson? (the merge-fields dict, JSON-serialized).

NotificationDelivery field detail

NotificationId? (links back to the in-app row when both channels were delivered), RecipientUserId, Channel (always Email currently), Status (Queued/Sending/Sent/Failed/Bounced/Rejected), Attempts, LastAttemptAt?, NextAttemptAt?, ProviderMessageId?, ErrorMessage?, Subject?, Body, Recipient? (email address).

NotificationPreference field detail

UserId, TemplateKey, Channel, IsEnabled. Missing rows = enabled (opt-out, not opt-in).

NotificationService API

Application/Services/NotificationService.cs:

PublishAsync(string templateKey, Guid recipientUserId, IDictionary<string,object?> mergeFields,
             string? link = null, CancellationToken ct = default);

PublishToManyAsync(string templateKey, IEnumerable<Guid> recipientIds, IDictionary<string,object?> mergeFields,
                   string? link = null, CancellationToken ct = default);

PublishToPermissionAsync(string templateKey, string permissionKey, IDictionary<string,object?> mergeFields,
                         string? link = null, Guid? excludeUserId = null, CancellationToken ct = default);

Steps:

1. Look up the user → respect PreferredLanguage for primary/secondary template choice.
2. Auto-inject user.fullName, user.email, user.code, user.userName, and link into the merge-fields dict (caller values win via TryAdd).
3. Render subject + body via the regex \{\{\s*([\w\.]+)\s*\}\}. Pre-replace   and   to plain space (admin Quill editor injects these — without normalization the merge regex misses placeholders).
4. For InApp: strip HTML tags + decode entities → plain text → INSERT Notification.
5. For Email (if user.Email exists and channel enabled): keep HTML → INSERT NotificationDelivery with Status = Queued.

NotificationDeliveryWorker (Infrastructure, hosted service): polls NotificationDeliveries where Status = Queued AND (NextAttemptAt is null OR NextAttemptAt <= now), claims a BatchSize chunk, calls IEmailSender.SendAsync(...). Retries up to MaxAttempts with exponential backoff. Marks Sent/Failed/Bounced accordingly.

SmtpEmailSender reads its config live from EmailProviderSettings (singleton row), decrypts the password via IDataProtector, applies the RedirectAllToAddress if RedirectAllEnabled (staging escape hatch), and prefixes the subject with the original recipient address so testers can tell who each redirected mail was meant for.

Operations

Notification templates (Application/Features/NotificationTemplates/)

My notifications (Application/Features/Notifications/)

My preferences (Application/Features/NotificationPreferences/)

NotificationEventCatalog

Application/Services/NotificationEventCatalog.cs is the source of truth for which template keys exist + which merge fields the system passes for each. Used by:

• The admin "Available templates" list (so an admin doesn't invent a key the system never publishes).
• Documentation in this section.

Every event currently in the catalog:

Plus auto-injected on every event: user.fullName, user.email, user.code, user.userName, link.

Documents

Polymorphic file-attachment system.

Entities

Document: file metadata (NamePrimary, FileName, MimeType, SizeBytes, StorageKey, Sha256, UploadedBy, UploadedAt, ScanStatus (Pending/Clean/Infected/ScanFailed), Category (Invoice/Warranty/Manual/Photo/Certificate/AuditEvidence/Other)). The actual bytes live on disk via IFileStorage.

DocumentLink: DocumentId, OwnerType (Asset/AssetTransfer/WorkOrder/MaintenanceRequest/AuditResult/AuditResultLine/User/Organization/Vendor/CheckOut), OwnerId, LinkedBy, LinkedAt. A document can be linked to multiple owners; deleting a link doesn't delete the document.

Operations (Application/Features/Documents/)

There is no built-in virus scan integration — ScanStatus stays Pending forever unless an external job updates it. The frontend ignores the field; admins can wire a custom scanner if needed.

Reporting

Per-page filterable reports backed by hard-coded query handlers in Application/Features/BusinessReports/. Each one has a paged GET and a matching XLSX/PDF export, gated by per-report granular permission keys.

Each has a Get*Query + Export* path that uses IReportExporter (Infrastructure) → XLSX or PDF via QuestPDF. Export endpoints additionally check report.{key}.export-excel or report.{key}.export-pdf based on the format query param.

Per feedback_permission_granularity, what was previously a single report.read was split per-report (e.g., report.audit-history.read, report.audit-history.export-excel, report.audit-history.export-pdf). The generic report.read is in DatabaseSeeder.obsoleteKeys.

Settings

System-wide configuration tables. Administered via /settings/* pages.

HierarchyConfig + HierarchyLevel

One HierarchyConfig per EntityType (Location/Organization/Classification). Each has 1–5 HierarchyLevel rows defining LevelNumber, LabelPrimary/Secondary (e.g. "Building", "Floor", "Room"), and CodeDigits (padding width for the per-level code segment).

AppSettings

Singleton (id = 11111111-1111-1111-1111-111111111111). Fields:

Translation

Admin overrides for UI translation keys. The frontend's translations.ts is the source of truth for defaults; this table only stores edited rows. Active map = bundled defaults merged with Translations rows.

EmailProviderSettings

Singleton (id = 22222222-2222-2222-2222-222222222222). Drives the SMTP email pipeline. Fields documented in the entity's XML doc (above) — key flags:

• Enabled — master switch; when off the worker idles
• RedirectAllEnabled + RedirectAllToAddress — staging mode (every email goes to the test inbox)
• BatchSize, PollIntervalSeconds, MaxAttempts — worker tuning

System

Cross-cutting system tables not owned by any module.

AuditLogEntry

Append-only change log written by AuditLogInterceptor. Not a BaseEntity — no soft-delete, no Code/RowVersion. Fields:

Auditable entities are flagged in AuditLogInterceptor (entity allowlist). The interceptor runs before AuditInterceptor so it sees the original Deleted state (vs the rewritten Modified after AuditInterceptor flips it for soft-delete).

Retention: 7 years (per product requirement). Cleanup is operator-scheduled, not built-in.

RequestLog

Per-request access log written by RequestLoggingMiddleware (see 01). Fields covered there.

Retention: 90 days — same operator-driven cleanup pattern.

There is no controller for RequestLog — the LoginAuditController is sometimes confused for it but only surfaces LoginAudit rows. Direct DB queries.

CodeSequence (Persistence-internal)

Not a domain entity — lives in Persistence/Entities/. Backs CodeGeneratorService.NextSequenceAsync. Fields: Id, EntityType, Period (e.g. "2026"), LastValue. Read with WITH (UPDLOCK, ROWLOCK) to serialize concurrent inserts. See 01 §Code generation.

Where to go next