PLAN.md — Luga ModuleManager

Executable roadmap. Phases, checklists, recorded decisions, risks. Updated as deliveries progress. Items are small enough to become an isolated PR.

1. Overview

Build Luga ModuleManager — Brazilian B2B multi-product SaaS platform for SMBs — in incremental phases, starting with a solid foundation and ending the MVP with 3 sellable modules (Core + Customers + Payments).

Guiding principle: each phase has a testable, deployable, demonstrable deliverable. No "invisible foundation for 3 months". Even Phase 0 ends with something deployed to staging.

2. Decisions Made (ADR summaries)

#	Decision	Rationale	Status
001	Modular Monolith Extractable	Integrated Suite with monolith simplicity + future microservices option	✅
002	Suite (not Federation)	SMB ICP requires cohesive UX; shared core entities	✅
003	.NET 10 + ASP.NET Core 10 + EF Core 10	Latest LTS stack, performance, Microsoft tooling	✅
004	Azure SQL Database Serverless	100% Microsoft stack, auto-pause saves on MVP	✅
005	Microsoft Entra External ID (single tenant + tenant_id claim)	Microsoft stack, scales for SMBs, low cost	✅
006	Azure Container Apps + GHCR public	Scale-to-zero, low cost, aligned with future extraction	✅
007	GitHub Actions with OIDC	No secrets, modern standard	✅
008	Bicep for IaC	Native Azure, simple, no state	✅
009	Controllers (not Minimal APIs)	Developer decision — more conventional	✅
010	MediatR (not Mediator source-gen)	Huge community, better for Visual Studio	✅
011	Mapperly (not AutoMapper)	Source-gen, no reflection, explicit	✅
012	Repository Pattern with generic base	Developer decision — wrapper over EF	✅
013	EF Core Interceptors (not override)	Composable, testable, modern Microsoft pattern	✅
014	LugaDbContextBase in BuildingBlocks.Infrastructure	Reuse without violating cross-module architecture	✅
015	Schema per module on SQL Server	Physical isolation, prepares for extraction	✅
016	Outbox per module	Each module takes its outbox when extracted	✅
017	Custom Result	No exception for business flow	✅
018	TimeProvider for testable time	.NET 8+ standard	✅
019	Customer in Customers module (not core)	Rich entity, evolves a lot, isolates for extraction	✅
020	Visual Studio 2022 17.12+	Developer decision	✅
021	Mailtrap for transactional email	Generous free tier	✅
022	Manual WhatsApp via wa.me in MVP	Free, no onboarding	✅
023	Asaas as primary gateway (V2 covered)	BR focus, immediate Pix, competitive fees	✅
024	Own billing via Stripe/Asaas/Mercado Pago	No dogfooding in MVP	✅
025	Frontend: Nx monorepo + Next.js 15 + React 19	Modern standard, strong AI tooling	✅
026	Single web app with 3 areas (marketing/dashboard/admin)	Integrated UX, simple for MVP	✅
027	Mobile via Expo + React Native in V1.1+	Logic reuse via shared packages	✅
028	PWA enabled from Phase 0	Basic mobile at no extra cost	✅
029	Subdomains: luga.com / app.luga.com / api.luga.com	Clear context separation	✅
030	Custom fields as JSON column	Performant on SQL Server, queries via JSON_VALUE	✅

3. Explicit TBDs (to be defined)

Topic	When to decide
Exact plan pricing (Starter / Pro / Business)	Close to launch, based on validation
Chosen gateway to charge own tenants	Phase 1 start (Stripe / Asaas / Mercado Pago)
Feature flags tooling	V2, when justified
Backup and DR policy	Before production (end of Phase 1)
Detailed LGPD compliance (DPO, exclusion flow)	Before public launch
Customer support (Intercom, Crisp, custom)	Before public launch
Product analytics (PostHog, Mixpanel)	V1.1+
Status page (Statuspage.io, Instatus)	V1.1+
Terms of use and privacy policy	Before public launch
Automated WhatsApp (Z-API vs Cloud API)	V2
Mobile apps (iOS + Android)	V1.1+

4. Out of MVP Scope

To avoid scope creep, EXPLICITLY not in MVP:

❌ Documents module (DMS) — V2
❌ Signatures module — V2
❌ Dedicated CRM module — V3
❌ NF module (NFS-e) — V3
❌ End customer portal — V4
❌ Unified messaging (Talk) — V4
❌ Scheduling — V5
❌ Financial/Income statement — V5
❌ Native mobile app — V1.1+
❌ Actions engine (generic automation) — V2
❌ Automated WhatsApp via API — V2
❌ Stripe Connect (international billing) — V2
❌ Multi-gateway in Payments (only Manual + Asaas in MVP) — V2 adds Pagar.me/MP
❌ Full white-label (per-tenant colors/brand) — V3
❌ Public Luga webhooks for external systems — V2 (with Actions)
❌ Public API for external devs — V3
❌ Extension marketplace — V3+

5. PHASE 0 — Foundation

Goal: build complete technical foundation supporting all future modules, with infrastructure deployed to staging. No business features yet — just plumbing.

Definition of done: base API runs on staging Container App, authenticates via Entra External ID, persists to Azure SQL, frontend runs on localhost showing functional login.

Estimate: 4-6 weeks (solo dev) / 2-3 weeks (with pair).

5.1 Repository Setup

(S) Create luga-ModuleManager repo on GitHub (private initially)
(S) .gitignore for .NET + Node + Visual Studio + Rider
(S) .editorconfig configured for Visual Studio + StyleCop
(S) Initial README.md with description and how to run locally
(S) Copy CLAUDE.md and PLAN.md to repo root
(S) Set branch protection rules on main (require PR, require CI)

5.2 Backend: Solution and Projects

5.3 BuildingBlocks.Domain

5.4 BuildingBlocks.Application

5.5 BuildingBlocks.Infrastructure

5.6 Core Module (minimum to authenticate)

5.7 Bootstrapper

5.8 Aspire (.NET AppHost)

(M) Luga.AppHost project
(M) Compose: SQL Server (container) + API + Hangfire dashboard
(S) Document in README how to run (dotnet run --project src/AppHost)

5.9 Tests

5.10 Frontend: Nx + Next.js

5.11 Infra: Bicep

5.12 CI/CD

5.13 Phase 0 Definition of Done

✅ API runs locally via dotnet run --project src/AppHost
✅ Login works via MSAL → Entra External ID → API validates JWT
✅ POST /api/tenants/register creates tenant and populates JWT with tenant_id
✅ GET /api/users/me returns logged user data with correct tenant_id
✅ ArchUnitNET passes in CI
✅ Integration tests pass in CI (Testcontainers)
✅ Auto deploy to staging when merging to main
✅ Next.js frontend running on localhost showing login + dashboard placeholder
✅ Hangfire dashboard accessible at /jobs (authenticated)
✅ Application Insights receiving logs and metrics

6. PHASE 1 — Complete MVP

Goal: sellable product. Tenant can sign up, choose a plan, manage customers, configure billing plans, manually mark payments OR integrate with Asaas, and send billing notifications.

Definition of done: 1-3 beta tenants using in production, processing real charges.

Estimate: 8-12 weeks (after Phase 0).

6.1 Core: Pricing System (modules + tiers + bundles)

6.2 Core: Own Billing (Luga's recurring fees)

(S) Decide gateway: Stripe / Asaas / Mercado Pago
(M) Integration with chosen gateway
(M) Webhook receiver for confirmed payment
(M) Update of TenantSubscription.Status based on payment
(M) Default handling (suspends tenant after X days)
(S) Frontend: tenant invoice history (in dashboard area)

6.3 Customers Module

6.4 Payments Module

6.5 Pre-production Hardening

(M) Rate limiting configured per tenant + per IP
(M) Audit log for sensitive actions (refund, cancellation, value change)
(M) Automatic Azure SQL backup configured (point-in-time restore)
(M) Terms of use and privacy policy (publish before launch)
(M) LGPD/GDPR: implement personal data deletion (LGPD Art. 18)
(M) Internal status page (even if simple — /health/ready exposed publicly)
(M) Application Insights alerts (error rate, latency, webhook failures)
(S) Documentation for tenants (FAQ, tutorials)
(S) Internal technical documentation (runbooks)

6.6 Phase 1 Definition of Done

✅ Tenant signs up, chooses plan, pays Luga's subscription via own gateway
✅ Tenant creates customers (with custom personalized fields)
✅ Tenant defines billing plans and associates customers
✅ System automatically generates invoices according to periodicity
✅ Tenant manually marks invoices as paid OR receives via Asaas
✅ Billing notifications generated and sent (email + manual WhatsApp)
✅ 1-3 beta tenants using in real production
✅ Test coverage >80% in Domain and Application
✅ No data leaks between tenants in E2E tests
✅ Performance OK: p95 of requests <500ms
✅ Basic tenant documentation available

7. Risks and Mitigations

#	Risk	Probability	Impact	Mitigation
1	Microsoft Entra External ID too complex for SMB	Medium	High	Robust custom claims provider; ultra simple signup; E2E flow tests
2	Asaas API unstable or slow subaccount approval	Medium	High	ManualPaymentGateway always works as fallback; document avg time
3	Custom fields JSON column causes slow queries with volume	Low	Medium	Computed indexes in SQL Server; fallback to EAV table if becomes problem
4	Multi-tenancy: bug leaks data between tenants	Low	CRITICAL	Mandatory E2E tests for every CRUD; ArchUnitNET; double code review
5	Poor performance of Mapperly + EF Core in large queries	Low	Medium	Regular profiling; query splitting; AsNoTracking where possible
6	Container App cold start affects UX	Medium	Medium	min_replicas=1 in production; staging stays at 0
7	Azure SQL Serverless cold start after pause	High	Low	auto_pause_delay=1h in prod; warmup during business hours
8	Azure costs running away	Medium	Medium	Azure Cost Management alerts; weekly review for first 3 months
9	MediatR licensed lib (paid version)	Confirmed	Medium	Current free version still works; plan fork or alternative if needed
10	Small team (1 dev) delays MVP	High	Medium	Aggressively cut scope; early beta releases for feedback
11	LGPD: not meeting data deletion deadlines	Low	High	Implement deletion flow in Phase 1; document process
12	Asaas webhook loses messages	Medium	High	Idempotency via unique ExternalEventId; manual replay via dashboard

8. Definition of Done (per item)

A checklist item is considered done when:

✅ Code implemented and compiling without warnings
✅ Unit tests covering new logic
✅ Integration tests if feature touches persistence or API
✅ ArchUnitNET passes
✅ Code review approved (own dev if solo, with pair if in team)
✅ Documentation updated if public contract changed (Contracts or API)
✅ Migration reviewed if schema changed
✅ Staging deploy works
✅ Smoke test in staging passes
✅ Item marked as - [x] in this PLAN.md

9. Next Steps (V1.1 and beyond)

For after MVP is running, in likely order:

V1.1 (month +1 to +3 after MVP)

Mobile app (Expo) with login + basic dashboard + mark payment
More sophisticated default handling (dunning policies)
CSV customer import
Report export (CSV, PDF)
Multi-gateway: Pagar.me or Mercado Pago as second provider
Basic customer portal (V4 anticipated if feedback asks)

V2 (month +4 to +6)

Documents module (DMS)
Signatures module (electronic signature)
Actions engine (generic automation)
Automated WhatsApp via Z-API
Public API for integrations (with docs in Scalar)

V3 and beyond

Dedicated CRM module
NF module (NFS-e)
Complete end customer portal
Unified messaging (Talk)
Schedule (appointments)
Cash (financial/income statement)
Extension marketplace (V3+)

10. How to Update This PLAN

Mark items as - [x] as delivered
Add new items in phases as you learn
Move items between phases if priority changes (but record in history)
Add new decisions in section 2 (ADRs)
Update TBDs as decided
Review risks every sprint
History of important changes at the bottom of this file

Change History

2026-05-03: Initial creation of PLAN.md consolidating all architecture, stack, and roadmap decisions.

FilesExpand file tree

PLAN.md

Latest commit

History