Architectural decisions

Context

The most-shipped pattern for serious B2B SaaS in the 5-50 engineer range is a modular monolith — one deployable, well-bounded internal modules, an event log for the patterns that benefit from async. Microservices solve organizational scaling problems most CleenUI customers don't have; they pay the latency, ops, and debugging tax for capabilities they don't need.

Decision

CleenUI ships as 14 vertical-slice modules (M01-M14) inside a single ASP.NET Core 8 deployable. Cross-module communication is in-process. Background work runs as Azure WebJobs + Azure Functions, organized as a 12-project Visual Studio solution.

Alternatives considered

• Microservices (one service per module). Rejected: operational complexity not justified by team size.
• Single 'big-ball-of-mud' monolith (no module boundaries). Rejected: that's exactly what the codebase is trying to NOT be.

Context

Most .NET shops reach for EF Core by reflex. CleenUI predates EF being a serious option for the workload (writes were already in flight when EF Code First matured) and the team made an explicit choice to not adopt it once EF became viable. Stored procedures give you: query plans the DBA can read and tune, parameter-sniffing control, server-side transaction logic, security boundary at the procedure level (apps can't write ad-hoc SQL), and zero ORM-impedance-mismatch for complex projections.

Decision

All reads and writes go through 700+ hand-tuned stored procedures via Dapper + ADO.NET. Migrations are scripted T-SQL files checked into the repo. POCOs are mapped by Dapper. No DbContext, no IQueryable, no LINQ-to-SQL.

Alternatives considered

• Entity Framework Core 8. Rejected: query plans are opaque, migrations are surprising, and complex projections fight the ORM.
• Dapper without stored procedures (inline SQL in C#). Rejected: loses the security and tuning benefits.

Context

Microsoft pushed Blazor hard for .NET teams. It's a reasonable choice for shops that need end-to-end C#, but the React ecosystem dwarfs Blazor in component libraries, hiring pool, and third-party integration coverage. For B2B apps that need real visual polish + accessibility + a large component surface, React wins on selection alone.

Decision

Single React 18 + Vite frontend. 61 components in 12 categories. No Blazor, no Angular, no MAUI. CleenUI is a TypeScript-ready JSX codebase; the typings ship with the component library.

Alternatives considered

• Blazor Server / Blazor WASM. Rejected: smaller ecosystem, larger bundles, harder hiring.
• Angular. Rejected: heavier framework, smaller hiring pool than React.
• Multiple frontends (one per surface). Rejected: maintenance multiplier.

Context

Identity is a category where 'build it yourself' is almost always wrong. The threats evolve faster than internal teams can keep up with (MFA bypass, credential stuffing, token replay), and the compliance surface (SAML, SOC 2, etc.) is significant. CleenUI customers ship multi-tenant B2B apps where identity is a hard requirement on day one.

Decision

Auth0 + JWT is the default identity provider. OIDC, social-login providers (Google, Microsoft, GitHub, Apple), MFA, and password-reset flows are wired end-to-end. The Auth0 management API is also used for organization-tenancy provisioning when needed.

Alternatives considered

• ASP.NET Core Identity. Rejected: rolling our own MFA and social-login was not worth the time.
• Microsoft Entra (Azure AD B2C). Rejected: less flexible per-tenant configuration than Auth0.
• Keycloak (self-hosted). Considered for high-volume customers — kept as a swap-in option.

Context

Multi-tenant data isolation is the most common source of catastrophic data leaks in B2B SaaS. App-layer filters ('WHERE account_id = @currentAccount') are the standard pattern but fail catastrophically when a developer forgets the filter on one query. The CleenUI domain (B2B SaaS, audit-heavy, regulated industries) cannot afford that failure mode.

Decision

Every queryable table has an account-scoping column. The data layer enforces account scoping at the stored-procedure entry points — the application role cannot execute ad-hoc SQL bypassing it. Cross-account queries require a specific elevated role (admin or impersonation context).

Alternatives considered

• SQL Server row-level security (RLS) policies. Considered — kept as a complementary layer for the most sensitive tables.
• Per-tenant database. Rejected: 14 modules × N tenants × backup-and-migration overhead doesn't scale operationally.

Context

i18n is usually done with .resx files (static keys translated at build time) or string-table tables (one row per key, language column). Both fail when content itself is user-editable — a customer renames a category, that rename needs to translate to 30 languages without a code change.

Decision

Every translatable entity has a sibling `<Entity>Language` table with per-language overrides. A translation registry tracks which entities have pending translations, dispatches them to the configured machine-translation provider, and caches results. Adding a new language is a configuration row, not a schema change. Adding a new translatable column on an existing entity is a one-line registry update.

Alternatives considered

• Static .resx files. Rejected: doesn't handle user-editable content.
• Single string-table with composite keys. Rejected: lookup hot path is much slower than indexed sibling tables.

Context

Cache invalidation is one of the two hard things. A single-layer cache (in-memory only) can't share across API instances. A single-layer distributed cache (Redis only) pays a network round-trip on every read. The hot path is reads of slow-to-compute aggregates; the right answer is a small in-process cache backed by a shared distributed cache.

Decision

Layer 1 is Microsoft.Extensions.Caching.Memory per process (sub-ms reads). Layer 2 is Azure Redis Cache shared across all API instances + WebJobs. Invalidation is wired into the data-access wrappers around every write stored procedure — on a write, the wrapper invalidates both layers for the affected keys. Cache keys are prefixed with `accountId` for per-tenant isolation.

Alternatives considered

• In-memory cache only. Rejected: doesn't share across instances.
• Redis only. Rejected: network round-trip on every hot-path read.

Context

Microsoft + .NET shops default to Azure; AWS and on-prem are common for regulated customers. The codebase needs to make Azure the cheapest path to a deploy, while not locking out customers who need to run elsewhere.

Decision

Default hosting targets are Azure App Service / Container Apps (API), Azure SQL Database (DB), Azure Functions + WebJobs (background work), and Azure Redis Cache. Every Azure-specific binding (Storage Queues, Service Bus, Blob storage, App Insights) lives behind a thin abstraction so the deployment target can swap to AWS SQS / S3 / CloudWatch / RDS without touching domain code.

Alternatives considered

• AWS as the default. Rejected: most CleenUI customers are .NET-first / Microsoft-first, and Azure-default reduces friction.
• Cloud-agnostic from day one (no Azure-specific bindings). Rejected: cost of abstraction without commensurate benefit for the common case.

Context

A licensed codebase of CleenUI's depth (524 endpoints, 300+ tables, 14 modules, custom integrations) is not something a team adopts cold. Either the architect is involved at the kickoff or the team spends 60+ hours rediscovering the architecture by reading code. Neither is the customer's preferred outcome.

Decision

Every CleenUI engagement starts with a no-cost 30-minute architecture review. Pricing is custom-scoped per engagement, not a fixed-price license. The architect (Shawn Livermore) is the named delivery contact and remains involved through go-live.

Alternatives considered

• Self-serve license + community support. Rejected: doesn't match the codebase depth.
• SaaS subscription. Rejected: codebase is the product, not a hosted service.