Artha Fintech Operations — Engineering Onboarding

2026-09-17 · @Someone

Everything a new engineer needs before their first pull request: what the system does, how it is put together, what it is built with, and how we use Claude Code to add to it.

1. What the platform does

Artha Fintech Operations is the platform Artha Fintech runs its business on. Everything the company does sits in one of two halves: work done for customers, and work done inside the company.

Naming note. The code is still called OpsLayer — the solution is OpsLayer.sln, the projects are OpsLayer.Api, OpsLayer.Domain and so on, and the database is opslayer. "Artha Fintech Operations" is the product; "OpsLayer" is the codebase. Don't rename anything in the repository.

Each app owns a database schema and is referred to internally by a module code. There is no M2 — don't go looking for it.

Part 1 — Customer Apps

These deal with Artha Fintech's customers: who they are, what they bought, what we run for them, and what is going wrong.

How they join up. A customer in CRM is the anchor. Cloud Ops and Support both route by the CRM connection registry, Delivery links by customer_id, and all four surface on Customer 360 — one page showing that customer's contract, money owed, cloud health, open tickets and delivery state together. Any new customer-facing feature should carry a customer_id so it appears there too.

Part 2 — Internal Apps

These deal with Artha Fintech itself: its people, its money, and the platform the other apps stand on.

The two ideas that hold it together

The attention hub (M0). Every app pushes whatever needs a human into one scored, assigned, escalating feed. The newcomer's instinct is to build a bespoke alert list for their own app. Don't. Raise an attention item and it lands in the same place as everything else, with the same ownership, escalation and audit.

The customer hub (M0 + M5). m0.customers plus the M5 customer_connection registry is how Cloud Ops and Support find a customer's real systems. A connection with no connector_instance_id is in local mode — derived or seeded data, no live credential.

Who uses it

Artha staff, imported automatically from Microsoft 365 — the majority. Customer users, who see only their own organisation's data, across a three-tier hierarchy: Artha sees everything, a customer sees itself and its own end customers, an end customer sees only itself.

2. Architecture

A .NET 8 API and a React SPA over one PostgreSQL database. Dependencies run one way only:

flowchart LR
  SK[SharedKernel] --> D[Domain] --> A[Application] --> I[Infrastructure] --> API[Api]

Each project has per-module folders. Application holds requests, handlers and pure rules and can never touch a database directly. Infrastructure holds EF configuration, workers and external clients. Unit tests reference Application only, which is what keeps the rules testable without a database.

The request pipeline, in order

This is the single most useful thing to understand. Every request goes through it, and most "why is this 403 / 404 / 428" questions are answered by knowing which stage fired.

flowchart TD
  H[HTTP: CORS, auth] --> PM[PrincipalMiddleware] --> RL[Rate limiter] --> C[Controller]
  C --> SA[SecurityAudit] --> V[Validation] --> AU[Authorization] --> SU[StepUp] --> TX[Transaction] --> HA[Handler]

The rate limiter sits after PrincipalMiddleware on purpose: it partitions on the ops_uid claim the middleware stamps. PrincipalMiddleware also requires a live server session from X-Session-Id on every path except session start.

Then five MediatR behaviours, outermost first:

One DbContext, per-module interfaces

OpsDbContext is split into partials (OpsDbContext.M5.cs and so on). Handlers depend on a module interface, and the interfaces inherit: IOpsDb ← IHrDb/IAccDb ← ICrmDb ← ICloudDb/IDeliveryDb ← ISupportDb. So a support handler can read CRM tables, but a CRM handler cannot read support tables. Names are snake_case; the migrations history table is m0.__ef_migrations.

How modules talk to each other

• Shared reads. Any module may query another's tables directly — M6 and M7 both read m5.customer_connection. Cross-schema id columns are plain columns with no EF foreign key. Keep new links unenforced the same way.
• Events, not calls. To notify another module, a domain entity calls Raise("opslayer.mX.thing.happened", …), which writes to m0.outbox; a worker polls it and uses m0.inbox for idempotency. Modules never call each other's handlers — the one exception is M7 escalation calling M1's WorkItemBuilder.
• Background work. PeriodicWorker subclasses, registered under Workers:Enabled. Each waits 30 seconds before its first tick, then runs each tick in its own scope as a system principal.

3. The security model

Read this section twice. It is the part of the codebase where a well-meant change does real damage, and a hardening pass (documented in docs/m0-hardening.md) deliberately removed every second route to access. Don't put one back.

EffectiveScope.Allows is the single enforcement point. One method, in SharedKernel/Principal.cs, answers every access question:

Allows(permission, companyId?, teamId?, customerTenant?)

Four rules follow from it, and all four are load-bearing:

1. Never branch on a role name. No Roles.Contains("Admin") anywhere. Permission keys only. A source scan fails the build if you try.
2. IsPlatformAdmin is the only bypass — group scope plus m0.platform.admin. Never add a second shortcut.
3. Platform-only keys (*, m0.platform.admin, m0.tenant.manage, m0.grant.write) are never carried by a company-scoped grant.
4. Out of scope reads like non-existent. A denied query returns 404 or an empty page, never an error that confirms the record exists.

Who gets access, and how

That last row is the only customer-level boundary in the system, added in September 2026. It is enforced in exactly one place — CrmAccess.VisibleAsync — which every M5, M6 and M7 read funnels through. Everything else scopes by company.

Rules in one place

Application/M0/Security.cs holds the security rules as pure functions: GrantRules, ModuleOwnership, AttentionAccess, AccountOwnerAccess, StepUpLockout, SecurityConfigRules, NetworkRules, SecretScrubber. Extend these rather than writing checks inline — that is what makes them unit-testable and reviewable.

Three more things that bite

• Company-targeted M0 handlers must re-check. ScopeHelper.EnsureCompanyAccess(p, r) has to be the literal first statement of the handler, with the parameter named exactly as the scan expects. Rename the parameter and the build fails.
• Outbound calls go through the "connectors" HttpClient: no redirects, public IPs only (re-resolved to defeat DNS rebinding), and .RemoveAllLoggers(). Connector URLs carry credentials in the path. A test proves the leak returns if you remove that call.
• Secrets are never in the repo. They live in dotnet user-secrets locally and environment variables in deployment. A source scan checks every appsettings*.json for credential-shaped keys.

4. Technologies used

Versions below are the pinned ones. Every package is pinned to an exact version — a source scan fails the build on a floating range, so don't add ^ or *.

Backend

Frontend

Infrastructure

PostgreSQL 16, Docker (one multi-stage image: node build → dotnet publish → runtime serving the SPA from wwwroot), Railway for deployment, Microsoft Entra ID for sign-in and Microsoft Graph for the directory sync. Tests are xUnit with FluentAssertions.

Two dependency advisories are knowingly open (NCalcSync, react-router v6). Both need major upgrades. Read docs/m0-hardening.md A06 before "fixing" them.

5. Running it, and the gates

Secrets are not in the repo. Before anything works, set them once per machine:

cd src/backend/OpsLayer.Api
dotnet user-secrets set "ConnectionStrings:Postgres" "Host=…;Database=opslayer;Username=…;Password=…"
dotnet user-secrets set "Secrets:LocalKey" "<32 random bytes, base64>"

Then pick one:

docker compose up --build          # everything: web :8080, API :5080, Postgres :5432

cd src/backend && dotnet run --project OpsLayer.Api --urls http://localhost:5080   # API from source
cd src/web && npm ci && npm run dev                                                # SPA, port 5173 only

The API auto-migrates and seeds reference data at every start. Startup refuses unsafe configuration — if it exits with Unsafe configuration: …, that is SecurityConfigRules doing its job, not a bug. A wildcard CORS origin aborts in every environment.

Tests

dotnet build src/backend/OpsLayer.sln -c Release     # what CI runs
dotnet test  src/backend/OpsLayer.sln
npm run typecheck                                    # the only web gate

• Unit tests reference Application only, so nothing there can touch a database. They cover rule classes, state machines and parsers.
• Integration tests boot the real API in a throwaway opslayer_it_<guid> database on the server named in OPSLAYER_TEST_PG, and drop it afterwards. Clients start real sessions and complete step-up with a software passkey, so signatures are genuinely verified. Only Microsoft's token validation is faked.
• Performance tests are opt-in (OPSLAYER_PERF=1) because they seed ~170k rows.

Five source scans that fail the build

These scan the repository itself, in tests/OpsLayer.UnitTests/SecurityTests.cs. New code must satisfy all five:

1. No SQL built from strings. No FromSqlRaw/ExecuteSqlRaw, no NpgsqlCommand from an interpolated string. Use interpolated FromSql, or a const statement with bound parameters.
2. Authorization never checks a role name. Permission keys only.
3. Every company-targeted M0 request is re-checked in its handler, with ScopeHelper.EnsureCompanyAccess(p, r) as the literal first statement and the parameter named exactly.
4. Committed configuration holds no secrets. Any credential-shaped key, or anything under ConnectionStrings:, must be empty.
5. Every package is pinned to an exact version.

Tests are sentences

Name them as claims, not labels: Heartbeat_extends_idle_never_absolute_and_the_absolute_limit_always_wins. Use a FluentAssertions because string whenever the assertion encodes a business rule. Security tests carry the control id (A01_…).

6. Building a feature with Claude

Claude Code has written most of this codebase, and it works well because the repository is set up to make it work. Understanding that setup is the difference between getting a good feature and getting a plausible-looking mess.

Why it works here

CLAUDE.md at the repository root is loaded into every session automatically. It carries the architecture, the coding standards, the pipeline table, the feature recipe and the gotchas. You do not need to re-explain the codebase in your prompt. If you learn something a future session would need, add it to CLAUDE.md — that file is infrastructure, not documentation.

The five source scans matter more than they look. They are guard rails Claude cannot talk its way past: if it writes raw SQL or branches on a role name, the build fails. Machine-checked conventions beat written ones.

The workflow

flowchart TD
  A[Describe the outcome] --> B[Ask for a plan first]
  B --> C[Read and correct the plan]
  C --> D[Approve, then it builds]
  D --> E[Build + tests + typecheck]
  E --> F[Review the diff yourself]

1. Describe the outcome, not the implementation. "Account owners should see only their own customers' data" beats "add a CustomerScope property to EffectiveScope". It knows the codebase; it does not know your intent.

2. Always ask for a plan first on anything non-trivial. The phrase that works: "properly plan this and show me — after my approval you can start building." The plan is where mistakes are cheap. A real plan for this codebase should name the files it will touch, the migration it will generate, and which existing rule it has to respect.

3. Correct the plan. This is the highest-leverage minute you will spend. A plan that says "hide the menu item" when routes are unguarded is wrong, and catching that in the plan saves a rewrite.

4. Make it follow the seven-step recipe. Every feature in this codebase goes the same way, and the recipe is in CLAUDE.md:

1. Domain — entity and state machine in OpsLayer.Domain/Mx/. Raise outbox events for anything another module cares about.
2. Application — request record and handler together in one file. [OpsAuthorize("mx.perm")], IQuery for reads, IScopedRequest plus EnsureCompanyAccess when it targets a company, [RequiresStepUp] for anything sensitive. Pure logic goes in a static rule class.
3. Infrastructure — EF configuration in the module's OpsDbContext.Mx.cs partial; workers and external clients in Infrastructure/Mx/.
4. Migration — dotnet ef migrations add <Name> -p OpsLayer.Infrastructure -s OpsLayer.Api. Generated from the model, never hand-written.
5. Api — a one-line controller action. New permission keys go in Api/Seed/Seeder*.cs.
6. Web — endpoint via injectEndpoints, screen in src/features/<module>/, route in src/main.tsx.
7. Tests — unit tests for the rule class, an integration test for the endpoint's access rules.

5. Demand evidence, not assurance. Ask it to run dotnet build -c Release, dotnet test and npm run typecheck, and to show you the output. "It should work" is not a result. If it says a test passes, the count should be in the transcript.

6. Review the diff yourself. You own the code. Claude is fast and careful but it is not accountable — you are.

What to say when it goes wrong

• It guessed instead of checking. "Don't guess — query the database / read the file and tell me what it actually says." It has tools; make it use them.
• It fixed the symptom. "That hides the problem. What is the root cause?"
• It claims something works. "How did you verify that?" A good answer cites a command and its output.
• It went beyond the ask. Say so. Scope creep in a security-adjacent codebase is a real risk.

Three things to be careful about

• Security changes need proof, not reasoning. A change to EffectiveScope, ScopeResolver, CrmAccess.VisibleAsync or any behaviour needs an integration test that proves the boundary holds. If it cannot be run, say so out loud rather than shipping quietly.
• Migrations are irreversible in production. Read the generated migration before it is applied. Check it does not recreate another module's tables.
• It will happily write a plausible wrong answer about live state. Anything about what is deployed, configured or in the database should be checked, not recalled.

7. The delivery process, step by step

Every feature goes through the same eleven steps. Nothing here is optional — the steps people are tempted to skip (7 and 8) are the ones that cost the team later.

flowchart LR
  A[Understand<br/>steps 1-2] --> B[Prompt<br/>steps 3-5]
  B --> C[Build + test<br/>steps 6-7]
  C --> D[Document<br/>steps 8-9]
  D --> E[Review + release<br/>steps 10-11]

Where people go wrong

Step 7 gets skipped. The most common failure is treating a green build as a passed test. The build proves the code compiles and the rules hold; it says nothing about whether you built what was asked for.

Step 8 gets skipped. It feels like paperwork. It isn't — it is the difference between the next person's session starting informed or starting blind.

Step 6 gets started before step 4. Building before the prompt is reviewed usually means rebuilding.

If the change touches security

Anything that touches EffectiveScope, ScopeResolver, a MediatR behaviour, CrmAccess.VisibleAsync, a permission key or a grant needs a higher bar at steps 6, 7 and 10:

• an integration test that proves the boundary holds — not just that the happy path works, but that the denied path is denied;
• a named reviewer who has read docs/m0-hardening.md;
• and if the boundary could not be tested end to end, say so explicitly in the review rather than letting it pass quietly.

8. Where documents and prompts live

Everything you write on the way to a feature goes in one place:

Operations > Shared > Functional Documents > [your folder name] > upload documents

One folder per person. Upload at step 9, once the feature is built and tested — not before, so what you store is what actually shipped rather than what you first intended.

What to upload

Naming

Use something a stranger can search: the feature name and the date, for example account-owner-access-2026-09-17. Keep the prompt and its plan side by side under that name so the pair stays together.

Why this is worth doing

Prompts are the reusable part of this way of working. A good prompt for "add a screen with unit-based access" saves the next person an hour and, more importantly, produces a result that matches the house style rather than reinventing it. The folder is the team's library of what has already been figured out.

Two things it is not for: anything containing a secret, a connection string or a credential — those never leave user-secrets and the environment; and the code itself, which belongs in the repository with the pull request.

9. A worked example, and the traps

Worked example: account-owner access

A real feature, built in September 2026. The ask was one sentence: "when a user logs in, check whether any customers are assigned to him, then show my customers and give view access to that customer's data."

What made it work was the planning conversation, not the code:

1. The investigation came first. Before writing anything, the existing state was traced: does customer-level access already exist? Answer — ScopeKind.Customer existed in the model but no request implemented TargetCustomerTenant, so it was dead code. That one finding changed the whole design.
2. An ambiguity was resolved out loud. "All customer data" could mean all customers or all data of their customers. Guessing would have built the wrong feature or a security hole. Asking cost one message.
3. The design followed the architecture. One choke point — CrmAccess.VisibleAsync — because M5, M6 and M7 all read through it. One enforcement point, not fifteen sprinkled checks.
4. The rule went in a pure class (AccountOwnerAccess) with five unit tests pinning it: read-only keys, never platform keys, and never narrowing someone who already had wider access from a role.
5. The gap was stated, not hidden. The integration suite was blocked by an unrelated migration, so the boundary has no end-to-end test. That was reported rather than glossed over.

That last point is the habit worth copying. An unverified claim is worse than a known gap.

Traps that catch everyone

Where to read next