00 — System Overview

One-page entry point. Read this first; deeper docs link from here.

What this system is

The Asset Tracking System registers, monitors, transfers, maintains, and audits physical assets. It supports per-asset identification by QR code or manual code entry. The product is bilingual (English / Arabic primary, plus 9 secondary UI languages) with full RTL support.

This docs/ folder is the up-to-date reference for the system as implemented.

Top-level architecture

flowchart LR
  subgraph Clients
    A[Angular SPA<br/>desktop shell]
    M[Angular SPA<br/>mobile shell<br/>/mobile/*]
  end
  A -- REST/JSON over HTTPS --> API
  M -- REST/JSON --> API
  subgraph "ASP.NET Core 8 Web API"
    API[Controllers /api/v1/*] --> APP[Application layer<br/>MediatR handlers]
    APP --> DOM[Domain entities + interfaces]
    APP --> INFRA[Infrastructure<br/>JWT, password hash,<br/>permission resolver,<br/>code generator,<br/>file storage,<br/>email]
    APP --> PERS[Persistence<br/>EF Core + SQL Server]
  end
  PERS --> DB[(SQL Server)]
  INFRA --> FS[(AppData/Documents)]
  INFRA --> SMTP[(SMTP / configured<br/>email provider)]

The backend is a modular monolith: one deployable API process, internal module boundaries (Identity, Master Data, Assets, Audits, Transfers, Custody, Maintenance, Notifications, Documents, Reporting, Settings, System). Each module owns its domain folder, its EF configurations, and its Application/Features/<Module>/ handlers.

Solution layout

AssetTrackingSystem/
├── AssetTracking.slnx                ← solution file
├── docs/                             ← THIS DOCUMENTATION
├── src/
│   ├── AssetTracking.Domain/         ← entities, enums, base classes, interfaces (zero deps)
│   ├── AssetTracking.Application/    ← MediatR commands/queries, DTOs, validators, mappings, pipeline behaviors
│   ├── AssetTracking.Persistence/    ← EF Core DbContext, configurations, interceptors, migrations, seeders
│   ├── AssetTracking.Infrastructure/ ← JWT, password hashing, permission resolver, code generator, file storage, email
│   └── AssetTracking.API/            ← Controllers, middleware, RequirePermission attribute, Program.cs
├── tests/
│   ├── AssetTracking.Domain.Tests/
│   ├── AssetTracking.Application.Tests/
│   └── AssetTracking.API.Tests/
└── frontend/                         ← Angular 18 + PrimeNG 18 SPA
    └── src/app/{core,shared,layouts,features}/...

Tech stack

Core domain conventions

These apply to almost every entity. Detailed treatment in 01-backend-architecture.

BaseEntity

Every persisted entity inherits BaseEntity. Fields:

A global EF query filter on IsDeleted == false is applied to every entity in BaseEntityConfiguration. Use IgnoreQueryFilters() in admin/seed paths only.

Bilingual fields

User-facing strings come in pairs:

• NamePrimary / NameSecondary
• DescriptionPrimary / DescriptionSecondary
• FullNamePrimary / FullNameSecondary (User)
• SubjectPrimary / BodyPrimary + SubjectSecondary / BodySecondary (NotificationTemplate)

The "primary" / "secondary" terminology is language-agnostic — admins configure which language is which via HierarchyConfig and the App Languages page. Frontend uses the LocalizePipe to pick the right one for the active UI language. Bilingual data input fields use the appLangDir="primary|secondary" directive so each input picks the right text direction independent of the surrounding UI language.

Code generation

Auto-generated, human-readable codes via ICodeGenerator, implemented by CodeGeneratorService. Per-entity prefix table lives in that service; row-level locking (UPDLOCK, ROWLOCK) on the CodeSequences table prevents duplicates.

(Full source-of-truth: CodeGeneratorService._codeMap.)

RBAC — permission-based, never role-based

• Roles are cosmetic collections of permissions; business code checks permission keys, never role names.
• Resolution: effective = (∪ role permissions) ∪ (direct grants) − (direct denies). Deny wins.
• Endpoint enforcement: [RequirePermission("resource.action")] attribute on every controller action (or [AllowAnonymous]). Verified by a build-time reflection test.
• Frontend gates UI affordances with auth.hasPermission('...').
• Permission cache key: (UserId, SecurityStamp). SecurityStamp regenerates when role/permission grants change.

Granular keys live in PermissionSeeder.cs; obsolete keys are hard-deleted via DatabaseSeeder.obsoleteKeys. The system favors granular per-action permissions (e.g., report.audit-history.export-excel rather than a generic report.export).

Modules at a glance

flowchart TB
  IDENT[Identity & Access<br/>User, Role, Permission,<br/>UserRole, RolePermission, UserPermission,<br/>RefreshToken, LoginAudit]
  MD[Master Data<br/>Organization, Location, Classification,<br/>Vendor, Manufacturer]
  ASSET[Assets<br/>Asset, AssetDetails, AssetStatus,<br/>+ four history tables]
  AUDIT[Audits<br/>AuditPlan, AuditPlanScope,<br/>AuditAssignment, AuditAssignmentAsset,<br/>AuditResult, AuditResultLine, AuditReviewAction]
  XFER[Transfers<br/>AssetTransfer, AssetTransferLine]
  CUST[Custody<br/>CheckOut]
  MAINT[Maintenance<br/>MaintenancePlan + MaintenancePlanAsset,<br/>MaintenanceRequest, WorkOrder]
  NOTIF[Notifications<br/>NotificationTemplate, Notification,<br/>NotificationDelivery, NotificationPreference]
  DOC[Documents<br/>Document, DocumentLink]
  RPT[Reporting<br/>per-page filterable reports<br/>with XLSX/PDF export]
  SETT[Settings<br/>HierarchyConfig, HierarchyLevel,<br/>AppSettings, Translation, EmailProviderSettings]
  SYS[System<br/>AuditLogEntry, RequestLog]

  IDENT --> ASSET
  MD --> ASSET
  ASSET --> AUDIT
  ASSET --> XFER
  ASSET --> CUST
  ASSET --> MAINT
  AUDIT --> NOTIF
  XFER --> NOTIF
  MAINT --> NOTIF
  ASSET --> DOC
  AUDIT --> DOC

Frontend at a glance

frontend/src/app/
├── core/             ← singletons: services, interceptors, models, i18n, theme
├── shared/           ← reusable components, directives, pipes
├── layouts/
│   ├── main-layout/  ← desktop shell (top bar + side nav)
│   └── mobile-layout/← mobile shell (top bar only, simplified menus)
└── features/
    ├── auth/login/
    ├── dashboard/
    ├── users/{user-list, user-detail}
    ├── roles/{role-list, role-detail}
    ├── permissions/   ← read-only browser
    ├── master-data/{organizations, locations, classifications, vendors, manufacturers}
    ├── assets/{asset-list, asset-detail}
    ├── audits/{audit-plans, audit-plan-create, audit-plan-detail,
    │           my-audits, assignment-detail,
    │           pending-reviews, result-review}
    ├── transfers/{transfer-list, transfer-detail}
    ├── checkouts/
    ├── maintenance/{maintenance-plans, maintenance-plan-detail,
    │                maintenance-requests,
    │                work-orders, work-order-detail}
    ├── notifications/{notifications-inbox, preferences}
    ├── reports/{reports-hub, asset-inventory, audit-history,
    │            audit-results, transfer-history, maintenance-history,
    │            checkout-activity}
    ├── settings/{hierarchy-config, app-languages, translations,
    │             notification-templates, email-provider}
    ├── audit-log/, login-audit/, profile/
    └── mobile/{mobile-home, mobile-assignment, scan-audit}

Routing (app.routes.ts) gates each route with a permission guard except the login page and the mobile shell entry. The mobile shell auto-redirects desktop-typed users back to /, and MainLayoutComponent redirects userType === 'Mobile' users to /mobile. Cross-shell navigation pitfalls are documented in 04-frontend-architecture.

Communication patterns

Lifecycle conventions cheat sheet

• Adding a new entity: derive from BaseEntity → write EntityConfiguration : BaseEntityConfiguration<T> → add DbSet<T> to AppDbContext → add a code prefix to CodeGeneratorService._codeMap → write Create*CommandHandler (set Id = Guid.NewGuid() on every child) → write *Dto and mapping → add RequirePermission attributes on the controller endpoints → register the permission keys in PermissionSeeder → write the EF migration with dotnet ef migrations add.
• Adding a new permission: append to PermissionSeeder._permissions (with module + label + isDangerous + sortOrder) → if it replaces an old key, add the old key to DatabaseSeeder.obsoleteKeys.
• Adding a new notification template: insert into DatabaseSeeder._notificationTemplates with InApp + (optional) Email channel rows → reference merge fields by {{ namespace.fieldName }} → ensure the publishing handler pushes those fields into the merge dict; link and user.* are auto-injected by NotificationService.
• Adding a new module-level translation: append to frontend/src/app/core/i18n/translations.ts under the English block (others fall back via i18n.service.ts:59).

Where to go next