CognitixERP Developer Guide

1. Introduction

CognitixERP is a modular monolith ERP: one deployable API and one Blazor WebAssembly client. Business logic lives in backend modules; the UI talks to the API over HTTP and SignalR.

2. Big picture

At runtime there are two processes (development) or one public site (production same-origin):

Production same-origin (recommended)

https://yourcompany.com/           → WebApp (nginx / IIS static)
https://yourcompany.com/api/...    → API (reverse proxy)
https://yourcompany.com/uploads/   → file storage
https://yourcompany.com/chat-hub   → SignalR

WebApp ApiBaseUrl = site origin with trailing slash — do not append /api.

3. Solution structure

Open Source/CognitixERP/CognitixERP.sln in Visual Studio. Top-level layout:

CognitixERP.sln
├── apps/
│   └── Cognitix.WebApp                 # Blazor WASM + MudBlazor UI
│
├── src/
│   ├── Cognitix.API                    # HTTP host, controllers, PDF, middleware
│   ├── Cognitix.Billing
│   ├── Cognitix.Procurement
│   ├── Cognitix.Inventory
│   ├── Cognitix.POS
│   ├── Cognitix.Financials
│   ├── Cognitix.Banking
│   ├── Cognitix.CRM
│   ├── Cognitix.HRM
│   ├── Cognitix.Branching
│   ├── Cognitix.Compliance
│   ├── Cognitix.Users
│   ├── Cognitix.BiometricAgent         # Optional Windows HRM agent
│   └── Cognitix.CrossCuttingConcerns/
│       ├── Cognitix.Shared.DTOs
│       ├── Cognitix.SharedKernel
│       ├── Cognitix.Localization
│       ├── Cognitix.Notifications
│       ├── Cognitix.FileStorage
│       └── Cognitix.SyncContracts
│
├── lib/Cognitix.Licensing/             # Licensing DLLs (Setup Wizard, enforce, CognitiveCircle)
├── deploy/hetzner/                     # Linux nginx + systemd samples
├── tools/                              # Author migration scripts
├── test/                               # Unit, Integration, Performance, E2E
└── docs/
    └── Architecture.md

4. Request flow (end-to-end)

Typical authenticated API call from a Blazor page:

1. User opens route e.g. /billing/invoices → Razor page in Pages/Billing/
2. Page injects a WebApp service e.g. IInvoiceService from services/Billing/
3. Service uses injected HttpClient (factory name Cognitix.API)
4. AuthHeaderHandler attaches JWT; CultureHeaderHandler sends culture
5. Request hits API controller e.g. Controllers/Billing/InvoicesController.cs
6. Controller calls module Application service (validation, mapping, business rules)
7. Service uses module Infrastructure DbContext + repositories
8. Response returns DTO JSON → WebApp renders MudBlazor UI

5. WebApp (Blazor WASM)

Location: apps/Cognitix.WebApp/

Configuration

// apps/Cognitix.WebApp/wwwroot/appsettings.json
{
  "ApiBaseUrl": "https://localhost:7149/"
}

Trailing slash required. After Setup Wizard, copy the JSON from the completion screen into this file.

HttpClient pipeline

• Cognitix.API — authenticated calls (default injected client)
• Cognitix.PublicApi — login branding, anonymous endpoints
• Cognitix.AuthRefresh — token refresh (no auth handler — avoids recursion)

UI stack

• MudBlazor — tables, dialogs, forms, theme
• Localization — @inject ISharedLocalizer L from Cognitix.Localization
• Permissions — menu and pages hidden when role lacks page permission
• Culture / RTL — en-US, bn-BD, ar-SA (Arabic RTL)

Key routes

6. API host

Location: src/Cognitix.API/ — single ASP.NET Core host for all modules.

Controller modules (folders)

Controllers are grouped under:

Billing · Banking · Branching · Compliance · CRM · Dashboard · Financials · HRM · Inventory · Observability · Platform · POS · Procurement · Users

Composition root

Program.cs is the composition root: it registers DbContexts, application services, validators, PDF generators, hosted jobs, and cached query decorators. Cross-module orchestration (e.g. invoice posting → journal entry) is wired here via DI, not by modules referencing each other directly.

Configuration files

• appsettings.json — JWT, CORS, database provider, licensing, SMTP, cache
• appsettings.Development.json — local overrides
• Environment variables — COGNITIX_JWT_KEY, Cors__AllowedOrigins__0, etc.

7. Business modules

Each business module follows the same internal shape:

Cognitix.{Module}/
├── Domain/           # Entities, enums, domain interfaces
├── Application/      # Services, validators, mappers, use cases
└── Infrastructure/   # EF DbContext, repositories, Migrations/{SqlServer|PostgreSql|MySql}

BiometricAgent is an optional Windows desktop agent for biometric attendance devices — separate from the web stack.

8. Clean Architecture rules

1. Dependency flow: Domain ← Application ← Infrastructure ← API
2. WebApp decoupling: references only Shared.DTOs, SharedKernel, Localization
3. Business logic stays in Application / Domain — not in Razor code-behind or controllers
4. Cross-module calls use contracts in SyncContracts or are composed in API DI
5. No .resx in Domain/Application — localization strings live in Cognitix.Localization

9. Authentication & authorization

JWT authentication

Permission model

• Each UI page maps to a SystemPage key (e.g. Invoices, POSTerminal)
• Roles grant Create / Read / Update / Delete per page
• API: [RequirePermission("Invoices", PermissionActions.Read)] on controller actions
• Registry: ApiPermissionRegistry.cs maps controller names → page keys
• WebApp: menu and routes respect the same permission keys

Branch isolation

Users can be branch-scoped. API middleware and filters apply branch filters on queries. Company-wide admins see all branches; branch users see only assigned branch data.

License middleware

LicenseEnforcementMiddleware blocks API access when trial expired or license revoked. SignalR uses LicenseEnforcementHubFilter. Setup and login endpoints are [AllowAnonymous].

10. Database & Setup Wizard

Buyers choose one engine in Setup Wizard Step 1: SQL Server, PostgreSQL, or MySQL. All 12 module schemas live in one database (buyer-chosen name).

Configuration

{
  "Database": { "Provider": "SqlServer" },
  "ConnectionStrings": { "DefaultConnection": "" }
}

Provider: SqlServer (default), PostgreSql, MySql. Connection string is written by the wizard.

Migration order (12 DbContexts)

Licensing → Users → Branching → Financials → Billing → Procurement → Inventory → POS → Banking → CRM → HRM → Compliance

Runtime components

Setup Wizard steps

Authors extending schema

Set COGNITIX_DATABASE_PROVIDER=PostgreSql|MySql|SqlServer before dotnet ef. Bulk regenerate: tools/setup-multi-db-migrations.ps1 (authors only).

11. Licensing & BuyerBuild

In the CodeCanyon package, licensing is delivered only as DLLs — not as editable source under src/.

Where the binaries live

lib/Cognitix.Licensing/
  Cognitix.Licensing.Application.dll
  Cognitix.Licensing.Domain.dll
  Cognitix.Licensing.Infrastructure.dll

Publish / build the API with -p:BuyerBuild=true so Cognitix.API references these HintPath DLLs. The sample deploy.yml detects this layout automatically when the lib/ folder is present.

What the DLLs provide at runtime

• Setup Wizard at /setup (database prepare, admin create, activate / trial)
• CognitiveCircle: activate, verify, heartbeat (https://api.cognitivebd.com)
• License enforcement (API middleware + SignalR hub filter)
• 72h offline grace only when CognitiveCircle is unreachable
• Admin revoke → immediate lock on next heartbeat / re-verify (not 72h grace)

ERP config ships Licensing:ProductSlug (not Envato Item ID).

12. Cross-cutting services

Cache

• Config: appsettings.json → Cache
• Registration: AddCognitixCachedQueryServices() — decorates read services
• Invalidation on master-data writes and journal post/reverse
• Diagnostics: GET /api/system/cache-probe (authenticated)
• No Redis in v1.0 — in-process only

13. Localization

UI strings live in Cognitix.Localization (hybrid model):

• SharedResource — common / nav / shared labels
• Module resources — e.g. CRM_*, Procurement_*, Billing_*

Cultures: en-US, bn-BD, ar-SA (RTL via MudRTLProvider).

Key shape: {Module}_{Context}_{Element} — e.g. Common_Save, Nav_HRM.

14. Cross-module wiring

Modules stay loosely coupled. Typical integrations:

Look for interfaces in SyncContracts and registration blocks in Cognitix.API/Program.cs when tracing cross-module behavior.

15. Where to change what

16. Add a new feature (checklist)

Example: add a simple “Customer Notes” list under Billing.

• Define CustomerNoteDto in Shared.DTOs
• Add entity + configuration in Cognitix.Billing.Domain / Infrastructure
• Add Application service methods (list, create, update)
• Register service in Cognitix.API/Program.cs
• Add CustomerNotesController with [RequirePermission(...)]
• Add page key to ApiPermissionRegistry and role management UI
• Add CustomerNoteService.cs in WebApp services/Billing/
• Add Pages/Billing/CustomerNotes.razor with route and nav link
• Add localization keys in Cognitix.Localization
• Authors: add EF migration for your provider; buyers: ship migration in product update
• Test: unit test Application service; manual test via WebApp + API

17. API surface (selected)

Product version is centralized in Directory.Build.props.

18. Testing

dotnet test Source/CognitixERP/CognitixERP.sln
dotnet test --filter Category=LicensingSmoke

Related install notes: Installation Guide, Troubleshooting FAQ (license / uploads).

19. Tech stack

• .NET 10 / ASP.NET Core / Blazor WebAssembly
• EF Core — SQL Server, PostgreSQL, MySQL
• MudBlazor, FluentValidation, MediatR
• QuestPDF (MIT-pinned), SignalR
• Serilog, JWT auth, in-process IMemoryCache

Third-party inventory: package root LICENSES.md / NOTICE.txt.

20. What v1.0 is not

21. Please Contact us

1. Sign up at https://cognitivebd.com
2. Create a Support Ticket.
3. Within 48hr we will reply.

Or email support@cognitivebd.com with your purchase code, version, and screenshots/logs.