FLX-ENG-RFC-001 — Branching, Build & Release Engineering¶

TL;DR — The decision¶

Maintain exactly one product codebase on a trunk-based branching model. Handle client-specific behaviour through tenant-aware configuration and feature flags, not through client-specific branches or builds. For offline / semi-connected client sites, ship the same artifact with a Flexli-signed deployment manifest that activates the correct feature set per customer.

Branches manage software lifecycle; tenancy manages customer variation; the deployment manifest carries entitlement.

1. Problem¶

Flexli is moving from a single-customer baseline (currently carrying Meesho-specific defaults) to a multi-client product line. Without a deliberate engineering process, the natural drift is toward per-customer code forks, per-customer branches, and per-customer builds. That path looks fast for the first three customers and becomes the single largest source of incidents, merge debt, and release risk by customer ten.

Current constraints¶

• The baseline codebase carries Meesho-specific defaults — not scalable to other clients
• Only prod and dev branches with short-lived feature branches — no formal branching model
• Gaps in publishing, bundling, and deployment — no CI/CD, no container image, no artifact signing
• Client variation is in business logic itself, not only configuration values

Design principles (each future proposal that violates one needs an explicit waiver)¶

1. Branches model lifecycle, tenants model customers. Branching expresses change delivery; tenancy expresses business segmentation. Mixing them creates merge debt.
2. One codebase, one artifact, multiple activations. The pipeline produces a single versioned artifact; customer differences are activated at deployment time through governed configuration.
3. Control lives with Flexli, not the customer. Feature entitlement is generated, signed, and shipped by Flexli. Customer-editable plain settings are not a control surface; operability and rollback are first-class concerns.

2. Branching Model¶

Trunk-based development with short-lived feature branches and on-demand release branches.

Branches¶

Rules¶

• Direct pushes to main are blocked; every change lands through a PR with green CI and at least one reviewer (two for release/* and hotfix/*)
• Feature branches rebase on main daily and merge within five working days
• Tags follow semantic versioning, cut from a release/* branch
• We do not create: customer/<name> branches, long-lived develop branches, or environment branches

3. Multi-tenant Architecture¶

Client-specific behaviour is expressed through four mechanisms, in this order of preference:

What we do not do: edit source per client; maintain client forks; rebuild the artifact per client.

Feature registry and manifest¶

All flags live in a single feature registry in code, each entry declaring key, owner, default, and dependencies. The per-client manifest references those keys. A manifest is a small signed JSON:

{
  "tenantId": "meesho-blr-wh-01",
  "site": "BLR_WAREHOUSE",
  "version": "1.2.3",
  "features": {
    "awb_data_sync": true,
    "manifest_close": true,
    "manual_sort": false
  },
  "config": {
    "api_base_url": "https://api.meesho.com",
    "data_sync_interval_seconds": 300
  },
  "validityWindow": {
    "notBefore": "2026-06-01T00:00:00Z",
    "notAfter": "2026-12-31T23:59:59Z"
  },
  "signature": "<cosign-detached-signature>"
}

The application validates the signature at startup and refuses to start on a tampered or expired manifest.

4. Build, Artifact, and Deployment¶

Pipeline stages¶

Build → Test → Scan → Package → Promote → Deploy → Verify

Online vs offline client deployment¶

Rollback¶

• Code rollback: redeploy the previous tagged artifact (retained at least three releases back)
• Config rollback: redeploy the previous signed manifest (manifests are versioned and immutable)
• Every release has a documented rollback criterion (error rate, latency, business KPI) and a named on-call owner

5. Technology Stack¶

6. Release Engineering Process¶

Two cadences¶

• Continuous to Flexli-managed environments: every merge to main that passes CI is deployed automatically to dev → staging → Flexli-internal pilot site. If canary metrics hold for 30 minutes, promoted further.
• Scheduled to client sites: fixed train tied to the sprint. One MINOR release per sprint, PATCH hotfixes only when needed.

Sprint-aligned release train (2-week sprint)¶

DORA + one Flexli metric¶

1. Deploy frequency — many merges/day to Flexli envs; ≥ 1 client release per sprint
2. Lead time — commit → first production tenant; target < 2 weeks
3. Change-failure rate — < 15%
4. MTTR — < 1 h cloud, < 1 day on-prem
5. Tenant-attribution rate — share of incidents diagnosed via per-tenant telemetry without manual log diving

What we deliberately don't do¶

• No release branches kept alive between sprints (release/X.Y is archived once shipped)
• No manual QA sign-off on every PR — automation is the gate; manual QA owns the rc and canary
• No release committee — a rotating Release DRI per sprint owns the call

7. PoC — Distribution Management Server¶

What already exists (§10.1 from RFC)¶

• A working strategy seam. Program.cs already registers IStrategy and IDropOffStrategy implementations for Flexli, Myntra, MyntraSingleScan, CsvClient, LiveClientServer, X1G3, WTM. Client variation is already an interface, not a branch.
• A clean DI container. ASP.NET Core DI is the natural place to bind a tenant manifest to the right strategy at startup.
• Configuration is already file-driven. appsettings.json and configuration.json exist; today they are flat and client-editable. The PoC converts them into a Flexli-signed manifest validated at startup.

What is missing (§10.2 from RFC)¶

• No CI, no Dockerfile for production, no signed artifact
• No tenant manifest (strategy selection is hardcoded by configuration values the client can edit on disk)
• No per-tenant observability (App.Metrics counters are present but emit global counters; nothing is tagged with tenantId)
• Framework is .NET 6 (out of LTS since Nov 2024)

PoC week plan¶

Decision gates (G1–G5)¶

Kill criterion: if porting to .NET 8 or extracting tenant variation from configuration.json requires touching more than ~30% of services or controllers, pause and re-scope the manifest model before continuing.

8. Definition of Success¶

Implemented successfully when all hold simultaneously:

• One main branch in active use; no per-customer branches exist or are required
• Every release is a tagged, signed, immutable artifact paired with a signed tenant manifest
• Onboarding a new tenant is a manifest change, not a code change
• Per-tenant telemetry queryable by tenantId across logs, metrics, and traces
• Rollback drills run quarterly and pass within the documented RTO
• Two tenants live on identical artifacts as evidence the model scales without forks