Welcome to the
stc pay Bahrain Middleware

Welcome to the team — take a breath. You have just opened one of the largest systems stc pay Bahrain runs: a 117-project .NET solution that sits between the stc pay mobile apps and roughly forty banks, card schemes, telcos, remittance networks and government services. It looks enormous from here, and that is completely normal. Nobody holds it all in their head — not on day one, and not after a year. You will learn the parts your tickets touch, and this guide will help you find the rest.

This is the document I wish I’d had on my first morning. It explains what the system is, how the code is organised, and how a request, an integration call and a background job actually move through it — always pointing at real files and classes so you can open them yourself. Read it with the solution open beside you.

How to pace yourself

You don’t need to read this front to back. Here’s the order that gets you productive fastest.

Contents

• A · Start here
• §01Welcome & how to pace yourself
• §02What the middleware is & does
• §03Architecture at a glance
• B · The codebase map
• §04The project map
• §05Tech stack & versions
• §06Conventions
• C · Getting it running
• §07Prerequisites & access
• §08Clone, configure, build, run
• §09Environments & configuration
• D · How it works
• §10Startup & hosting
• §11The request & data flow
• §12The data layer
• §13Cross-cutting concerns
• E · Walkthroughs
• §14A customer API request, end-to-end
• §15An outbound integration call
• §16A background processor, end-to-end
• §17The data & domain layer in action
• F · Working here
• §18API contracts & surface
• §19Data models & schema changes
• §20Integrations catalog
• §21Background jobs catalog
• §22Deployment & CI/CD
• §23Observability & runbook
• §24Branching, versioning & release
• §25Glossary & first-week cheat-sheet

Let’s start with the big picture: what this middleware actually is, and the job it does every second of the day.

In one line: the middleware is the brain of stc pay Bahrain — it owns the customer wallet and ledger in SQL Server, and it brokers every interaction between the mobile apps and the outside financial world.

The stc pay mobile apps never talk to a bank, a card scheme or a remittance partner directly. They call this system over HTTP, and it does the real work: authenticating the session, applying limits and fees, moving money on its own double-entry ledger, and — when value has to leave or enter the wallet — calling the right external rail and reconciling the result. Everything a customer can do in the app has a counterpart here.

The jobs it does

The surface is wide. A newcomer meets these domains first, and each maps to endpoint classes in StcPay.Middleware.Api/EndPoints/ and to one or more partner integrations:

Behind the request/response surface, a fleet of background services does the heavy, scheduled work the app never waits for: pulling card-clearing files over SFTP, running settlement, computing cashback and profit-share, generating statements, and dispatching notifications.

That’s the what. Next, let’s see the shape of it — and follow a single request from the phone to the database and back.

The one-sentence model: a thin web host receives a JSON request, hands it to a strongly-typed endpoint class, which runs business rules over an EF6 data-access layer and a fleet of HTTP partner clients, then returns a uniform CommonResponse envelope.

The moving parts

Six layers, each a family of projects. You’ll meet every one of them in this guide.

Lifecycle of one request

Here is the whole journey at altitude — we trace the real code for it in §14. A customer taps “Send money”:

1. The app POSTs JSON to api/mobile/v1/customer/SendMoney/transfer-money on the Panel IIS site.
2. An MVC route resolves it to SendMoneyController.TransferMoney(), which deserializes the body with ParseRequest<T>().
3. The controller calls into the business facade: ApiContext.SendMoney.TransferMoney(request).
4. The SendMoney endpoint validates the session GUID and device, checks limits, fees and balance.
5. It writes the double-entry transactions through the DAL (_dalcontext.Transaction.*) over the EF6 StcPayEntities context.
6. It returns a TransferMoneyResponse built by a ReasonResponse factory; the controller serializes it back to JSON.

With the shape in mind, let’s open the codebase and name every project you’ll see in Solution Explorer.

In one line: 117 projects, but only a couple of dozen are “core” — the rest are the ~40 partner clients (catalogued in §20) and the ~49 background jobs (§21). This section names the core projects you’ll open daily.

Everything lives in one solution, StcPay.Middleware/StcPay.Middleware.sln. Below, one project per row, grouped by layer.

Web hosts (deployed to IIS)

These are the only projects with a web-application project type — the processes IIS actually serves.

API, business & shared libraries

Referenced by the hosts; this is where most of your code-reading happens.

Data & infrastructure

The data model and the plumbing every layer leans on.

Payment gateways & QR

The card/scheme gateway family plus the standalone QR and PTS pieces.

Now that you can name the projects, let’s pin down the exact tools and versions they’re built on — and why each was chosen.

In one line: a classic .NET Framework 4.8 / EF6 / IIS stack — mature and stable rather than cutting-edge, with a deliberate small modern toehold.

Most of these versions come from packages.config files (the solution predates central PackageReference management). The “why” column is the part worth remembering.

Versions tell you the “what”. The conventions below tell you the unwritten “how” — the patterns the team expects you to follow.

In one line: naming tells you a project’s job, settings live in the database, and a handful of house patterns repeat everywhere — learn them once and the codebase becomes predictable.

Naming families

The project name is the fastest clue to what a thing does.

Build & project conventions

A few things that surprise newcomers: dependencies are managed with classic packages.config (~89 of them) — only the 3 SDK-style projects use <PackageReference>. EntityFramework 6.4.4 is the dominant pin. Almost everything is AnyCPU; only the three memory-heavy processors — UtilityProcessor, MPClearingProcessor and MainPaymentProcessor — are forced to x64. Output types split into 35 WinExe and 16 Exe background jobs, with the remainder being class libraries.

House patterns worth adopting

• Add a new outbound call as its own *.Communication.<Partner> library, following the existing static-client pattern.
• Read settings through ConfigurationSetting.<Key> (DB-backed), not Web.config appSettings.
• Return every API outcome through a ReasonResponse factory that builds a CommonResponse with a MiddlewareErrorCode and a localized message.
• Put kebab-case [JsonProperty("...")] on request/response DTOs so they match the mobile contract.
• Query through the readonly context (ReadonlyDataContext); save through the write context (DataContext).

Pitfalls to avoid

• Don’t look for an IoC container — there isn’t one. Services are reached through the ApiContext facade or constructed directly.
• Don’t add JWT/header auth to the mobile path — it authenticates by a session GUID carried in the request body.
• Don’t wrap multi-step writes in TransactionScope; the codebase uses DataContext.Database.BeginTransaction().
• Don’t regenerate an .edmx casually — it’s Database-First and the generated entities are referenced everywhere.
• Don’t trust branch-name spelling blindly — bgugfix/ and bufgix/ typos exist in history; match the team’s current convention.

That’s the lay of the land. Time to get it onto your machine.

In one line: a Windows + Visual Studio + SQL Server box, plus a set of credentials and connection strings you’ll need to ask your lead for.

Tooling to install

This is a .NET Framework / IIS world, so a Windows development machine is assumed.

• Visual Studio 2022 with the “ASP.NET and web development” and “.NET desktop” workloads (for MVC 5, Web API and Windows Services).
• .NET Framework 4.8 Developer Pack (the target of 114 projects).
• SQL Server (Developer/Express) with access to a copy of the stc pay databases — main, readonly and audit.
• MySQL client/server for the reporting database (the DataContextMySQL context).
• Redis reachable from your machine (local or a shared dev instance).
• IIS Express (bundled with VS) — the Panel host runs at https://localhost:44340/.
• Git with SSH access to git@github.com:stcpaybh/stcpay-middleware-dotnet.git.

With the tools in place, here’s the path from a fresh clone to a running app.

In one line: clone, open the solution, point the connection strings at a dev database, run the Panel host on IIS Express — and run any processor as a console app for debugging.

1. Clone and check out the branch your team works from (commonly Develop or UAT — confirm with your lead).
2. Open StcPay.Middleware/StcPay.Middleware.sln in Visual Studio 2022 and restore NuGet packages (right-click the solution → Restore NuGet Packages; these are packages.config projects).
3. Set the connection strings in the host’s Web.config (for the customer API that’s StcPay.Middleware.Panel/Web.config) — see §09 for the full list.
4. Make sure the Configuration DB table is populated — without it, ConfigurationSetting loads empty and partner calls fail silently.
5. Set StcPay.Middleware.Panel as the startup project and run (F5). It launches on IIS Express at https://localhost:44340/.
6. To debug a background job, set that processor (e.g. StcPay.Middleware.Service.RoundupsProcessor) as startup and run — it detects Environment.UserInteractive and runs its work in a console window instead of as a service.

# 1. clone
$ git clone git@github.com:stcpaybh/stcpay-middleware-dotnet.git
$ cd stcpay-middleware-dotnet
$ git checkout Develop

# 2. open in Visual Studio 2022, then restore + build from the IDE
#    (or, from a Developer Command Prompt:)
$ nuget restore StcPay.Middleware/StcPay.Middleware.sln
$ msbuild StcPay.Middleware/StcPay.Middleware.sln /p:Configuration=Debug

Running locally is one environment; the system lives across several. Here’s how configuration differs between them.

In one line: there are several environments (Dev, UAT, Pre-Production, Production), and the real configuration for each lives in a database table — not in Web.config.

Each long-lived branch (§24) maps to an environment. Connection strings are set per host in Web.config / App.config; everything else — partner URLs, keys, limits, feature toggles — comes from the database.

The connection strings

Five names recur across the solution. Set these and the contexts wire themselves up.

Settings live in the database

The single most important config fact: StcPay.Middleware.DataBaseConfiguration/ConfigurationSetting.cs is a static class with ~600 settings, loaded once in its static constructor from the SQL Configuration table (rows where IsActive = true). Partner URLs, API keys, JWT secrets, SFTP credentials, limits — all of it is read with ConfigurationSetting.<Key>, keyed by string.

static ConfigurationSetting() {
    var values = db.Configuration.Where(x => x.IsActive)
        .Select(y => new { y.ConfigurationKey, y.ConfigurationValue }).ToList();
    foreach (var item in values)
        switch (item.Key) {
            case "SmsHost": _smsHost = item.Value; break;
            // ... hundreds of cases
        }
}

You can now build and run it. The next group explains what actually happens when it’s running — starting with how each process boots.

In one line: web hosts boot through a classic Global.asax Application_Start; background jobs boot as Windows Services that loop forever — and neither uses a DI container.

When IIS starts the Panel app, StcPay.Middleware.Panel/Global.asax.cs runs. It’s a plain System.Web.HttpApplication (no OWIN Startup anywhere in the solution) that wires up Web API, routes, global MVC filters and bundles:

protected void Application_Start() {
    MvcHandler.DisableMvcResponseHeader = true;
    AreaRegistration.RegisterAllAreas();
    GlobalConfiguration.Configure(WebApiConfig.Register);
    FilterConfig.RegisterGlobalFilters(GlobalFilters.Filters);
    RouteConfig.RegisterRoutes(RouteTable.Routes);
    BundleConfig.RegisterBundles(BundleTable.Bundles);
}

Routing is convention-based — RouteConfig.cs maps the template api/{channel}/{version}/{short_code}/{controller}/{action}/{id}, and actions are picked by an [ActionName("kebab-case")] attribute. The customer “API” controllers are actually MVC controllers (a custom ApiController : BaseController) returning JsonResult, not System.Web.Http controllers.

Background services boot differently

Each processor is a console/Windows-Service executable. Program.Main either runs interactively (for debugging) or hands off to the Windows Service Control Manager; the service then spins a worker thread that loops, doing one unit of work per cycle:

protected override void OnStart(string[] args) {
    settproces = new Thread(new ThreadStart(StartProcessing));
    settproces.Start();
}
public void StartProcessing() {
    while (true && !_stopSignal) {
        try {
            DalContext dalContext = new DalContext();
            new CardSettlementProcessor(dalContext).StartCardSettlementProcessorService().Wait();
            dalContext.Dispose();
        } catch (Exception ex) { /* log */ }
        finally { Thread.Sleep(1000); }
    }
}

So a process is up and a request arrives. Let’s follow it through the layers.

In one line: a thin controller deserializes the body, calls one method on the ApiContext facade, and that endpoint does all the work — returning a uniform envelope.

Controllers carry almost no logic. They read the JSON body into a typed request with a ParseRequest<T>() helper and delegate straight to an endpoint:

[HttpPost, ActionName("transfer-money")]
public async Task<JsonResult> TransferMoney()
    => Json(await ApiContext.SendMoney.TransferMoney(ParseRequest<TransferMoneyCommonRequest>()));

ApiContext (in StcPay.Middleware.Api) is a god-object facade: its constructor uses an EndPointFactory to build ~50 endpoint objects — User, Card, SendMoney, Remittance, CashbackPocket, and so on — each extending MiddlewareEndPoint. The endpoint validates, applies rules, reads and writes through the DAL, and returns a response. There is no separate “service layer” for the customer API: the endpoint class is the business logic.

One envelope for everything

Every API method returns a CommonResponse (or a subclass) — the same three-field shape on the wire, with kebab-case JSON names:

public class CommonResponse {
    [JsonProperty("response-code")]    public int ResponseCode { get; set; }
    [JsonProperty("response-message")] public string ResponseMessage { get; set; }
    [JsonProperty("data")]             public object Data { get; set; }
}

The code comes from the MiddlewareErrorCode enum (Successful = 0, SessionExpired, InvalidGuid, …), and the message is localized. Responses are built by static ReasonResponse factories — e.g. TransferMoneyReasonResponse.InsufficientBalance(locale) — which is why endpoints return errors rather than throwing them.

The endpoints lean entirely on the data layer. Let’s open it.

In one line: EF6 over three Database-First models, fronted by a DAL facade that hands every DAO both a read-write and a readonly context, with raw ADO and Redis for the hot paths.

The four EF6 contexts all live in StcPay.Middleware.Data and are generated from .edmx files (Database-First — OnModelCreating throws UnintentionalCodeFirstException):

You rarely touch a context directly. Instead, DalContext (in StcPay.Middleware.DAL) is an IDisposable container that constructs one read-write and one readonly context and wires ~30 DAOs — Transaction, User, Card, RemittanceTransaction, and so on. The base DalRepository hands each DAO both contexts; the choice of which to use is made by the DAO method — reads against the replica, writes against the primary:

// read from the replica
var bal = await ReadonlyDataContext.ProspectStatementBalance
              .Where(x => x.ProspectId == id).FirstOrDefaultAsync();
// write to the primary
DataContext.Transaction.Add(transaction);
await DataContext.SaveChangesAsync();

For heavy or hand-tuned queries, DatabaseHelper (raw ADO — GetListQueryExecute<T>, ExecuteScalar<T>, a MySQL variant) runs query text with an optional command timeout and reflection-maps rows to objects. Caching goes through RedisContext (GetValue/SetValue/Remove over StackExchange.Redis). Multi-step writes that must be atomic use an EF6 transaction:

using (var tx = DataContext.Database.BeginTransaction()) {
    try { /* AddOrUpdate + SaveChangesAsync ... */ tx.Commit(); }
    catch { tx.Rollback(); }
}

Around all of this sit the concerns that touch every request — auth, logging, errors, security. That’s next.

In one line: three separate auth worlds, file-based NLog logging, errors returned (not thrown), and secrets that mostly live in the database — with a few hardcoded ones to be aware of.

Authentication — three worlds

This trips up everyone, so it’s worth stating plainly:

On the mobile path, the gate is a session lookup, not an attribute — the global AuthorizationAttribute filter is commented out, so each endpoint checks the session itself:

customerSession = await _apiContext.GetCustomerSession(request.SessionId);
if (customerSession == null || customerSession.Customer == null)
    return TransferMoneyReasonResponse.SessionExpired(request.Locale);

Logging

Logging goes through a small ILogProvider abstraction (note the Level enum’s charming Warring typo). The live implementation wraps NLog; you’ll see new NLog("SomeName") at the top of most classes, where the name becomes the per-logger file name. NLog writes file-only to D:/logs/StcPayMiddleware/${logger}_${date}.log with 50 MB rolling archives. A Bugsnag provider exists but is currently neutered (its constructor returns early).

Error handling

Endpoints try/catch and return a ReasonResponse rather than throwing — there is no Web API exception filter. The only global net is the MVC HandleErrorAttribute plus Application_Error in the Panel Global.asax, which logs the unhandled exception and redirects home. Panel also injects a per-request Content-Security-Policy nonce.

Security & secrets

Most secrets (partner keys, JWT secrets, SFTP credentials) come from the DB Configuration table via ConfigurationSetting. But a few are hardcoded in processor source — worth knowing and worth flagging:

That’s the whole machine in theory. Now we run four real flows through it, line by line.

In one line: we follow a wallet-to-wallet transfer from the phone to the ledger and back — the canonical money-movement path.

The endpoint is a POST the mobile app makes to:

POST /api/mobile/v1/customer/SendMoney/transfer-money

That URL resolves through the convention route in StcPay.Middleware.Panel/App_Start/RouteConfig.cs and the [ActionName("transfer-money")] attribute. Here is the journey:

1. Controller. SendMoneyController.TransferMoney() (Panel/Controllers/Api/SendMoneyController.cs) reads the body with ParseRequest<TransferMoneyCommonRequest>() and calls the facade.
2. Facade. ApiContext.SendMoney.TransferMoney(request) dispatches to the endpoint class SendMoney (StcPay.Middleware.Api/EndPoints/SendMoney.cs, ~line 1649).
3. Auth in-method. It parses the session-id GUID, loads the session via ApiContext.GetCustomerSession, and rejects an untrusted/unverified device.
4. Rules. It looks up the service (TransactionDAO.GetServiceByIdIfActive), enforces daily/monthly count & amount limits, computes fee + VAT, and checks the balance is sufficient.
5. Money movement. It creates two wallet transactions (sender + receiver) via TransactionDAO.CreateOrderTransactionWallet, links them with AddPeerTransactionMapping, and posts the double-entry AddJournal.
6. Safety net. A negative-balance guard reverses the journal and marks the transaction rolled back if the post would overdraw.
7. Response. It returns a TransferMoneyResponse from a TransferMoneyReasonResponse factory; the controller serializes it to JSON.

The controller really is that thin:

[HttpPost, ActionName("transfer-money")]
public async Task<JsonResult> TransferMoney() {
    try {
        return Json(await ApiContext.SendMoney.TransferMoney(ParseRequest<TransferMoneyCommonRequest>()));
    } catch (Exception ex) { _log.Error(ex, "..."); return Json(string.Empty); }
}

And the core posting — two transactions plus the journal — lives in the endpoint:

long txId = await _dalcontext.Transaction.CreateOrderTransactionWallet(/* sender */ …);
await _dalcontext.Transaction.AddTmsProcessorItem(txId);
long rxId = await _dalcontext.Transaction.CreateOrderTransactionWallet(/* receiver */ …);
await _dalcontext.Transaction.AddPeerTransactionMapping(txId, rxId);
if (!await _dalcontext.Transaction.AddJournal(senderId, peerId, txId, amount, rxId))
    return TransferMoneyReasonResponse.TransactionRollback(request.Locale);

That’s value moving inside the wallet. Next, value leaving it — an outbound call to a partner.

In one line: a remittance to RiaMoney — an OAuth2 bearer call over raw HttpClient, with an encrypted webhook coming back.

RiaMoney (StcPay.Middleware.Communication.RiaMoney) is a good representative: three small files, a static HTTP client, a cached OAuth2 token, and an inbound callback that’s AES-encrypted. Note it uses the BCL System.Net.Http — not RestSharp, and no request signing.

Outbound — create the remittance order

1. Business entry. RemittanceTransactionDAO.CreateRiaMoneyTransaction(request) is the entry point (called from Api/EndPoints/Remittance.cs).
2. Headers + token. PrepareRiaMoneyAPIHeaders() calls RiaMoneyAuthTokenService.GetValidToken() (an in-memory cache that refreshes with a 60-second expiry buffer) and assembles the subscription-key/host/authorization headers.
3. Transport. RiaMoney.RiaMoneyCommunicationWithQuery(...) builds the URL from ConfigurationSetting.RiaMoneyUrl, serializes the body, and calls SendHttpRequest — a fresh HttpClient with a 100-second timeout and a single attempt.
4. Result. The endpoint SendOrders/Order (PUT) creates the order; sibling endpoints draft, release, query, cancel and fetch rates.

RiaMoneyHeaderRequest headers = await PrepareRiaMoneyAPIHeaders();
string resp = await RiaMoney.RiaMoneyCommunicationWithQuery(
    createOrderRequest, null, headers,
    RiaMoneyNames.CreateTransaction, /* "SendOrders/Order" */
    MasterCardNames.Put, MasterCardNames.DefaultContentType);

Inbound — the encrypted status callback

Ria calls back to POST /api/…/ria-transaction-callback on the Panel host. The action is guarded by a [RiaMoneyAttribute] filter that decrypts the payload before the controller sees it:

// RiaMoneyAttribute.OnActionExecuting -> DecryptBase64Aes256Cbc
string key = ConfigurationSetting.RiaMoneyCallbackKey.PadRight(32, '$');
string iv  = ConfigurationSetting.RiaMoneyCallbackVector.PadRight(16, '$');
aes.Mode = CipherMode.CBC; aes.Padding = PaddingMode.PKCS7;  // AES-256

The decrypted payload becomes a RiaMoneyTransactionCallbackRequest, and RemittanceTransactionDAO.ProcessRiaMoneyStatusCallback maps the partner status, cancels/refunds or completes the local transaction, and awards loyalty points on success.

Requests and partner calls are the foreground. The background fleet does the rest — let’s trace one.

In one line: the Mastercard clearing processor pulls settlement files over SFTP, loads them, then matches each clearing record against an authorization and posts the money.

StcPay.Middleware.Service.MPClearingProcessor is a console executable with two files: Program.cs (entry) and ClearingProcessor.cs (~2,300 lines of logic). Unlike the looping services, it runs its pipeline once and exits — an external scheduler decides how often.

1. Entry. Program.Main news up a DalContext and a ClearingProcessor, then StartProcessing().Wait().
2. SFTP pickup. GetSettlementFiles uses SSH.NET to list /from_mpts for TXE* files, skips ones already in MpClearings (a raw-ADO EXISTS check via DatabaseHelper), downloads new ones, then deletes them from the server.
3. Decrypt + unzip. DecryptFile runs PgpCore PGP decryption and extracts the archive locally.
4. Load. PopulateDBFromExel parses the tab-separated file into MpClearings rows and bulk-loads them with SqlBulkCopy (serialized by a semaphore, with retry/back-off on transient SQL errors).
5. Settle. StartSettlement runs four phases (debit → cleanup → credit → refund cleanup); RunSettlementWorkers fans each phase across 4 workers in 200-record chunks.
6. Match & post. Settle(...) matches each clearing to an authorization in CardTransactionInformation and posts the settlement, refund or debit through the DAL — writing Transaction, TransactionActivity, MpClearingActions and marking CardTransactionInformationIsSettled.
7. Notify. It sends customer push notifications (“Account balance updated”, “Amount refunded”) and emails the Operations team on exceptions (“Auth Not Matched”).

// Program.cs — runs once, then exits
DalContext context = new DalContext();
ClearingProcessor processor = new ClearingProcessor(context);
processor.StartProcessing().Wait();

// SFTP pickup + dedupe + remote cleanup
sftp.Connect();
var files = sftp.ListDirectory("/from_mpts").Where(x => x.Name.StartsWith("TXE"));
// "SELECT CASE WHEN EXISTS (SELECT 1 FROM MpClearings WHERE FileName=@fileName) ..."
sftp.DownloadFile("/from_mpts/" + name, stream);
await DecryptFile(file, name);
sftp.DeleteFile("/from_mpts/" + name);

That’s the foreground, the partners and the background. They all converge on one thing — the data. Let’s watch it from the data’s point of view.

In one line: the same transfer from §14, seen from the database — which entities are written, in which store, and how the read/write split, audit DB and cache each play a part.

When SendMoney.TransferMoney posts a P2P transfer, TransactionDAO.CreateOrderTransactionWallet builds and persists a small graph of entities through the write context (StcPayEntities): an Order, one or more Transaction rows, and TransactionActivity ledger rows — then AddJournal records the double-entry movement. Reads taken along the way (limits, balances, peer lookups) prefer the readonly replica.

The core entities you’ll meet first

Three stores, three jobs

The same operation touches all three data stores, each with a clear role:

• Write DB (StcPayEntities) — the source of truth: orders, transactions, journals, balances.
• Readonly replica (StcPayReadonlyEntities) — queries, limit checks, statements and reports that shouldn’t load the primary.
• Audit DB (StcAuditTrailEntities1) — an isolated trail so audit writes never contend with transactional ones.
• Redis (RedisContext) — hot lookups; e.g. remittance corridors & banks are refreshed into the cache hourly by a dedicated service, so customer-facing reads stay fast.

The DalContext ties it together for a unit of work: it constructs the write and readonly contexts, exposes the DAOs, and disposes everything when the request or processor cycle ends. A background cycle is literally new DalContext() → do work → Dispose(), which is why a fresh EF change-tracker is created each iteration (and why huge batches re-new the context every 200 records).

You’ve now seen the system end to end. The final group is the reference shelf you’ll keep coming back to — contracts, schema, the full catalogs, deployment and the runbook.

In one line: the API “contract” is strongly-typed C# — request and response classes in StcPay.Middleware.Api — not OpenAPI; there’s no live Swagger and no URL versioning.

The Api library is organized by responsibility. Each folder has one job:

Routing isn’t declared here — the host controllers expose each method with [HttpPost, ActionName("kebab-case")] and bind the body manually with ParseRequest<T>(). The app-facing “version” is just the version field on CommonRequest; there are no /v1//v2 route segments (the api/v1 strings in the code are third-party partner URLs).

Endpoint classes by domain

A representative slice of the 47 — useful when you’re hunting for where a feature lives:

Those DTOs mirror database tables. Here’s how the schema itself is modelled and changed.

In one line: the database is the source of truth; the C# entities are generated from it via three EF6 EDMX models — this is Database-First, not Code-First migrations.

In StcPay.Middleware.Data there are three .edmx models, each producing a context and a set of generated entity classes:

How a schema change flows

Because it’s Database-First, the order is “database first, code second”:

1. The table/column change is made in SQL Server (by whoever owns DB changes — see the placeholder below).
2. A developer opens the relevant .edmx in Visual Studio and runs Update Model from Database.
3. EF regenerates the entity classes; the new entity or property becomes available to the DAOs.
4. DAO/endpoint code is updated to use it, and the change ships through the normal branch flow (§24).

The two biggest reference lists come next — every integration, then every background job.

In one line: every external partner the middleware talks to, one per row — your index when a ticket names a system you’ve never heard of.

These are the StcPay.Middleware.Communication.* libraries plus a few web-facing integration hosts. Direction is Out (stc pay→partner), In (partner→stc pay) or Both. “(inf.)” marks a purpose inferred from the project + main class rather than confirmed from config.

That’s who the middleware talks to. Next, what it does on its own schedule — the background jobs.

In one line: the ~50 background executables, grouped by how they run — constantly looping, on a daily timer, or one-shot under an external scheduler.

All are Exe/WinExe projects (mostly under StcPay.Middleware/Processors/). Looping and timer services host themselves as Windows Services; one-shot jobs are launched by an external scheduler (Windows Task Scheduler / SQL Agent) — so those cadences aren’t in the repo. Timer-based times are Bahrain-local.

Continuous-loop services

Long-running services that process work every few seconds to minutes.

Daily-timer services

Self-hosted services whose timer fires at a fixed Bahrain-local time, then re-arms for the next day.

One-shot jobs (external scheduler)

Run their pipeline once and exit; an external scheduler decides the cadence.

You know what runs and when. The last few sections are operational: how it ships, how you watch it, and how the team works.

In one line: it deploys to Windows — IIS sites for the web apps, Windows Services for the looping/timer jobs, and scheduled tasks for the one-shot jobs; the pipeline itself isn’t in the repo.

What you can tell from the code is the deployable shape. Each piece maps to a Windows hosting mechanism:

Builds are MSBuild / Visual Studio over packages.config (so a NuGet restore precedes the build). Remember the three x64 processors (§06) need an x64 build/runtime. Environments line up behind the branches (§24): work flows Develop → UAT → Pre-Production → Production.

Once it’s deployed, you need to be able to see what it’s doing. Here’s where to look.

In one line: observability today is mostly NLog files plus operational emails — so your first move in any incident is to read the right log file.

Where signal comes from

• NLog files — D:/logs/StcPayMiddleware/${logger}_${date}.log, one file per logger name, 50 MB rolling. The logger name is the string passed to new NLog("…"), so logs are grouped by component.
• Operational emails — e.g. the clearing processor emails operations@stcpay.com.bh on “Auth Not Matched” / “without posting” exceptions.
• Customer push notifications — many flows confirm success/failure to the customer (a useful cross-check that a path ran).
• Bugsnag — wired as a provider but currently disabled in code; don’t rely on it until re-enabled.

First-response runbook

Grounded starting points for the most common “it’s not working” reports:

Last stops: how changes are branched and shipped, and a cheat-sheet to keep by your keyboard.

In one line: long-lived branches map to environments and you promote work up the chain — the naming convention is loose, so follow the team’s current habit over the history.

The repo is github.com/stcpaybh/stcpay-middleware-dotnet. The branches you’ll care about:

Work flows up the environments: Develop → UAT → Pre-Production → Production. Topic branches are cut for features and fixes and merged back through review.

• Don’t mimic the historical spelling — you’ll see feature/, features/, Features/ and the typo’d bgugfix/ / bufgix/. Pick the team’s current convention and be consistent.
• Don’t assume SemVer tags gate releases — promotion is branch-based, not tag-based.

One page left — the glossary and a cheat-sheet to get you through week one.

In one line: the acronyms and partner names you’ll hear in stand-up, plus where to find things and what to aim for in your first week.

Domain glossary

Where do I find…?

Handy commands

# clone & pick your environment branch
$ git clone git@github.com:stcpaybh/stcpay-middleware-dotnet.git
$ git checkout Develop

# restore + build (Developer Command Prompt)
$ nuget restore StcPay.Middleware/StcPay.Middleware.sln
$ msbuild StcPay.Middleware/StcPay.Middleware.sln /p:Configuration=Debug

# find an endpoint by its app action name
$ grep -rn "ActionName(\"transfer-money\")" StcPay.Middleware/StcPay.Middleware.Panel

Your first week

• Get repo access and the connection strings / Configuration seed from your lead (§07).
• Build the solution and run the Panel host on IIS Express (§08).
• Trace one real request — open SendMoneyController → SendMoney.TransferMoney and read along with §14.
• Run one processor in console mode (e.g. RoundupsProcessor) and watch its NLog file.
• Skim the integrations (§20) and jobs (§21) catalogs so the names stop being mysterious.
• Pick up a small ticket — you’ll learn more from one real change than from re-reading this guide.