Solution architecture.
A system you can explain.

ClearLend should make one promise understandable: a borrower, lender or employee can complete an authorized action, the system preserves the relevant business rules, and someone can trace what happened afterward. This is a proposed solution architecture, not a claim that the application or its quality controls have already been implemented.

What we carry forward

• ClearLend operates a managed lending marketplace. It is not assumed to lend its own capital.
• Borrowers, lenders and operational teams have different permissions and information needs.
• Borrower interest, lender returns and ClearLend fees remain distinguishable.
• Offers preserve the exact terms shown when issued. Financial corrections create new records.
• A request sent to a payment provider is not proof that money moved.
• The educational build uses synthetic users, documents and simulated payments.
• The first vertical slice is a vetted borrower creating and submitting an application.

How to use this guide

Start with the system map for the big picture, then follow submission through the layers. Frontend and role chapters connect the code to real work. Azure, quality and testing show how we will prove the design. Select a chapter from the contents menu or use Previous and Next at the end of each chapter.

Angular presents role-specific experiences. It calls the API and never connects directly to SQL. The API maps requests to use cases. Those use cases authorize the action, invoke business rules and persist the outcome. Background processing handles work that must survive an HTTP request ending: notification delivery, reminders, reconciliation and integration retries.

A module owns its writes

Support may request a finance investigation through a defined application contract. It cannot change a payment table. Reporting consumes deliberate projections and never becomes a second route for changing business state. Modules can share a deployable host without sharing every implementation detail.

Why a modular monolith?

One initial application makes transactions, debugging, local development and releases easier to understand. The trade-off is coordinated deployment and shared runtime capacity. Boundaries require enforcement: folder names alone cannot prevent a tightly coupled application.

• Extract a capability when its scaling needs are measurably different.
• Separate a process when its failures must be isolated from interactive requests.
• Consider independent services when team ownership or security requirements justify the operational cost.
• Document processing and notifications are plausible candidates, but extraction still requires versioned contracts, data ownership and failure handling.

The arrows show source-code dependencies. At runtime a handler calls a repository interface and the infrastructure implementation executes SQL. The host composition root wires the implementations together. Dependency inversion lets business behavior remain testable without a database or web server.

A practical solution structure

src/
  ClearLend.Api/
    Endpoints/Applications/     # HTTP entry points
    Authentication/
    Composition/
  ClearLend.Application/
    Applications/CreateDraft/
    Applications/SubmitApplication/
    Applications/GetApplication/
    Authorization/
    Abstractions/
  ClearLend.Domain/
    Applications/ Products/ Offers/ Finance/
  ClearLend.Infrastructure/
    Persistence/Configurations/
    Persistence/Migrations/
    Documents/ Payments/ Notifications/ Outbox/
  ClearLend.Contracts/
  ClearLend.Worker/
    Outbox/ Reconciliation/ Reminders/
  ClearLend.Web/
    src/app/core/
    src/app/shared/
    src/app/features/
tests/
  Domain.Tests/ Application.Tests/ ArchitectureTests/
  IntegrationTests/ ContractTests/ EndToEndTests/
infra/
  modules/ environments/
docs/
  architecture/ decisions/ runbooks/

Vertical slices group the command, validation, handler and result around one user action. Separate module assemblies can follow when stronger compile-time isolation becomes useful. Initially, architecture tests check allowed namespace dependencies, while review rejects cross-module table writes and EF entities leaking into API responses.

Put behavior behind meaningful methods

Submit checks the current state and required facts. The handler obtains authoritative eligibility and evidence information first. A browser-supplied IsEligible flag is never the authority. The domain owns the invariant; the application owns obtaining the facts and coordinating the work.

application.Submit(submissionFacts, clock.UtcNow);

• Microsoft: common web application architectures and dependency inversion ↗

• Angular validates fields and presents an accessible error summary.
• The API establishes the caller’s identity; the use case verifies resource ownership and the permission to submit.
• Check an idempotency key and request fingerprint within the authorized user and operation scope.
• Load current vetting, credit limit, product version and evidence status.
• Invoke the domain transition using authoritative facts and the expected application version.
• Commit submitted state, audit entry, outbox item and replay result in one SQL transaction.
• Return Submitted — awaiting review with a reference number.
• A worker claims the durable outbox item and records the notification outcome.

Mutable facts require consistency too. A product pause or changed credit limit must not race unnoticed with submission. Use suitable transaction isolation or version checks for facts involved in the invariant. The product-pause policy must specify whether it blocks only new submissions or affects existing applications.

Concurrency and the outbox

Use SQL rowversion for optimistic concurrency and unique constraints for idempotency. Multiple instances must not rely on an in-memory lock. Claim outbox work using database leases and bounded batches so another worker can resume after a crash.

• Microsoft: transactional outbox principle (Cosmos DB example; ClearLend uses SQL) ↗

Use schemas such as applications, products, finance and servicing to make ownership visible. Schemas alone do not enforce architecture. Repositories, permissions and boundary tests support that ownership. A shared database and controlled EF Core unit of work simplify initial transactions, with coordinated migrations as an accepted trade-off.

Transaction boundaries and integrations

Application submission is a local transaction. A provider call happens outside it: first persist the intent, perform the external operation, then record the outcome. Authenticate callbacks, store a unique provider event ID, and update payment state, financial entries, audit and outgoing events atomically. Duplicate or out-of-order callbacks cannot regress a completed state.

Contracts define stable identifiers, money and currency, UTC timestamps, correlation IDs, idempotency, timeouts and error categories. Retry transient failures only when the operation is safe. Exhausted work enters an exception queue with an owner. Unknown payment outcomes initiate reconciliation rather than blind resubmission.

IPaymentGateway.InitiateFunding(...)
IPaymentGateway.GetOutcome(...)
IDocumentStore.OpenAuthorizedDocument(...)
INotificationSender.Send(...)

Private, versioned documents

Store content in private Blob Storage. SQL stores ownership, an opaque storage key, version, checksum, content type, scan status, review status and retention category. Authorize the upload intent, enforce limits, quarantine the file, scan it and expose the exact accepted version. The educational build can simulate scanning but must label it. Failed or unfinished scans remain unavailable.

The baseline downloads documents through authorized application access. This avoids giving a browser access to private storage endpoints. Replaced evidence retains its history and reason; retention and deletion follow approved policy and legal holds rather than keeping everything forever.

Terms and financial history

An accepted offer references immutable principal, currency, rate, term, fees, repayment assumptions, disclosures and acceptance evidence. Product edits create future versions. Corrections reference original financial entries and preserve actor, reason and approval. Balances derive from authoritative entries, with projections for fast reads.

/borrower/applications
/borrower/applications/:id
/borrower/loans/:id
/lender/products
/lender/portfolio
/operations/reviews
/operations/support
/operations/compliance
/operations/finance
/operations/servicing
/management/overview
/management/controls

Feature organization and state

Feature components own their forms and page-local state. Shared components provide accessible tables, pagination, status labels, money formatting, document summaries, timelines, confirmation dialogs and error summaries. Use reactive forms and typed API clients generated from a reviewed OpenAPI contract. Introduce a wider store only when state genuinely spans workflows.

Identity and the browser boundary

The proposed baseline serves Angular and the API from the same origin. ASP.NET Core handles external sign-in and issues a secure, HTTP-only session cookie. Mutating requests require antiforgery protection. Route guards improve navigation, while backend policies enforce access. Do not place sensitive responses in shared caches, and clear sensitive client state at logout.

Every screen has more than a happy path

• Loading: show progress without implying that an action has completed.
• Empty: explain whether there are no records or a filter has excluded them.
• Validation: focus an error summary, identify fields and preserve the user’s input.
• Conflict: explain stale state and offer a reload rather than overwriting someone else’s change.
• Failure: show a safe message and a correlation reference; never expose internals.
• Permission: do not reveal another customer’s record through error details.
• Financial data: distinguish confirmed, pending and projected figures, with a refresh time.

Accessibility is part of workflow design

Use semantic headings and labels, keyboard-operable controls, visible focus, sufficient contrast and status descriptions that do not depend on colour. Announce meaningful asynchronous outcomes. Test complete journeys with keyboard and screen-reader review, not only an automated page scan.

Choose a role below. The numbered rows highlight information that matters to that user. The action labels are illustrative wireframe controls, not a working lending application. In Read all mode every role is visible for comparison or printing.

These are annotated wireframes, not working finance controls. Values are illustrative. Risk/fraud, security/privacy and external-auditor roles remain later extensions.

The first App Service host serves Angular and ASP.NET Core. Hosted background handlers use SQL leases so scale-out does not duplicate ownership of jobs. ClearLend.Worker provides a separate host when background processing needs independent operation; only the intended processing host is enabled. For an App Service worker deployment, use a supported persistent hosting configuration and validate restart behavior.

Network and service access

The hardened design places a WAF-enabled Application Gateway in front of private App Service access. App Service private endpoints handle inbound connectivity; VNet integration handles outbound connections to private SQL, Blob Storage and Key Vault endpoints. Private DNS is part of the deployment. This is a production design option to price and validate, not a claim that the educational environment already has these controls.

Identity, secrets and infrastructure

Use managed identity for permitted Azure resource access and Key Vault for remaining secrets. API, worker, migration and pipeline identities have different privileges. Runtime identities cannot alter schemas. Staff privileged access requires MFA and controlled assignment. Use Bicep for resources, access, diagnostics, networking and environment parameters; use federated pipeline identity rather than committed credentials.

One artifact through the release pipeline

• Compile, lint and run relevant tests; scan dependencies and secrets.
• Build one versioned artifact and validate the infrastructure change.
• Deploy to UAT and run the critical journeys.
• Apply an approved backward-compatible production migration using a separate identity.
• Deploy the same artifact to the candidate slot with controlled processing behavior.
• Verify readiness and non-destructive smoke tests, then swap into production.
• Observe error rates, latency, outbox age and failed jobs against release thresholds.

Database compatibility and rollback

Use expand, migrate, contract: add compatible structures, migrate usage and data, then remove obsolete structures in a later release. Do not run migrations on every application startup. A slot swap can restore application code, but does not reverse data writes. Rollback depends on schema compatibility; destructive changes require a separate, rehearsed recovery plan.

Health, workers and resilience

Liveness verifies the process; readiness checks essential dependencies without triggering business actions. An email outage should alert operators without necessarily blocking submissions. For separate workers, deploy disabled, validate, then transfer ownership through controlled configuration and expiring leases. Rehearse this rather than relying on a single slot setting.

Higher availability requires a supported zone-redundant plan, sufficient actual app instances and resilient dependencies. Zone redundancy is not regional disaster recovery. Select tiers and recovery arrangements only after the service target and budget are agreed.

• Microsoft: baseline App Service architecture and private networking ↗
• Microsoft: deployment slots, swap behavior and settings ↗
• Microsoft: App Service managed identities ↗
• Microsoft: zone redundancy and actual application replicas ↗

Measure the whole system

RPO describes acceptable data loss; RTO describes acceptable time to restore service. State whether the scenario includes a region failure. Recovery must align SQL, documents, identity and pending provider operations. A successful SQL restore alone does not demonstrate application recovery.

A service objective is not a supplier SLA copied into a document. Measure the critical user journeys and their dependencies. When a target is missed, record whether the cause is code, query shape, capacity, provider behavior or an unrealistic assumption, then revise the appropriate part of the design.

Use the right environment for the claim

Run SQL Server integration tests for transactions, unique constraints and rowversion concurrency. An in-memory substitute cannot establish those properties. Simulated providers make fault cases repeatable, but real adapters later need provider contract and sandbox verification.

Place checks where they help delivery

• Every change: fast unit, application and architecture checks.
• Before merge or release: relevant database integration, authorization, contract and browser journeys.
• Before significant capacity changes: representative load and scale exercises.
• Before claiming readiness: release, rollback, alerting and restore rehearsals.
• Preserve results with the release so another engineer can inspect the evidence.

A decision-record template

ADR-005: Reliable follow-up work
Status: Proposed
Context: A committed submission must not lose its notification.
Options: Synchronous call; fire-and-forget task; transactional outbox.
Decision: Commit an outbox record with the application transition.
Consequences: Add leases, retry policy, deduplication and monitoring.
Evidence: Crash after commit, restart worker, recover pending work.
Owner: Backend lead
Review trigger: Delivery volume or routing requires a message broker.

An ADR is not a permanent prohibition on change. Revisit it when its context changes, and preserve the old record so the decision history remains understandable. Changes in service shape, funding model or privacy requirements should update the relevant decisions before they spread through code.

The first slice uses declared fixtures

Seed a synthetic vetted borrower, approved credit limit, published product version and accepted synthetic evidence. These fixtures let the first journey prove its boundaries without implying that complete onboarding or malware scanning already exists.

Educational implementation versus live launch

The build demonstrates real engineering behavior with simulated decisions and money. A live launch additionally needs a confirmed operating model and jurisdiction, approved agreements and disclosures, provider onboarding, real identity and evidence verification, privacy and retention decisions, accounting validation, independent security assessment, support ownership and tested recovery. Architecture diagrams do not supply those capabilities.

Phase 3 completion criteria

• Module ownership, layer dependencies and integration boundaries have been reviewed.
• Every established role has a permission scope and representative screen journeys.
• Submission specifies happy paths, failure paths, idempotency and concurrency.
• Environment isolation, slots, worker processing, migrations and rollback form one consistent release story.
• Quality targets have owners and are marked agreed or pending.
• Architecture decisions include trade-offs and revisit conditions.
• Blocking assumptions are resolved or explicitly constrain the implementation.
• The first vertical slice can be estimated and has executable acceptance criteria.

Continue into implementation

Phase 4 can establish the engineering foundation and domain model. Phase 5 can deliver the first complete vertical slice. Security, testing and deployment begin with that work; later readiness exercises prove and strengthen those controls. This keeps the series connected from product vision to working software and operational evidence.