From 2506a6745c1019731bbbb5441ad04d58b25892ec Mon Sep 17 00:00:00 2001 From: kevin-asprec Date: Wed, 4 Mar 2026 18:05:03 +0800 Subject: [PATCH] docs(01): capture phase context Phase 01: Foundation - Implementation decisions documented - Phase boundary established Co-Authored-By: Claude Opus 4.6 --- .planning/phases/01-foundation/01-CONTEXT.md | 72 ++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 .planning/phases/01-foundation/01-CONTEXT.md diff --git a/.planning/phases/01-foundation/01-CONTEXT.md b/.planning/phases/01-foundation/01-CONTEXT.md new file mode 100644 index 0000000..3815cc7 --- /dev/null +++ b/.planning/phases/01-foundation/01-CONTEXT.md @@ -0,0 +1,72 @@ +# Phase 1: Foundation - Context + +**Gathered:** 2026-03-04 +**Status:** Ready for planning + + +## Phase Boundary + +Containerized Docker dev environment, multi-tenant data isolation (PostgreSQL RLS), authentication with email/password, role-based access control for 5 user types (Admin, Office Staff, Collector, Technician, Client), tenant onboarding, super-admin tenant management, and unit test harness. No business features — this is pure infrastructure and auth. + + + + +## Implementation Decisions + +### Tenant Onboarding Flow +- Self-service signup — ISP fills out form and gets instant access +- Signup collects: business name, owner name, email, password, business address, contact info +- Single URL with tenant resolved from login (app.netforge.com) — no subdomains +- New tenants start empty — only pre-configured Chart of Accounts is auto-provisioned +- One email tied to one tenant (no cross-tenant accounts) + +### Login & Session Behavior +- Email/password only — no social login for v1 +- Self-service password reset via email link (forgot password → email → new password) +- Session duration: Claude's discretion (reasonable default) +- Session persists across browser refresh + +### Super-Admin Experience +- Claude's discretion on whether separate URL or same app with special view +- No tenant impersonation — view-only access to tenant information +- Super-admin sees per tenant: status (active/suspended), subscriber count, creation date, last activity, plus any other useful platform metrics (Claude's discretion) +- Tenant suspension with grace period (not immediate lockout) + +### Role Permission Boundaries +- **Multi-role support**: A single user can hold multiple roles (e.g., Technician + Collector). Permissions are the union of all assigned roles +- **Admin**: Full access to everything within their tenant +- **Office Staff**: Can create/manage users and assign roles. Can view financial reports but not modify Chart of Accounts or accounting settings. Can manage subscribers, billing, ticketing +- **Collector**: Can view all subscribers but can only record payments for subscribers in their assigned zone. Can log field collections and submit remittances +- **Technician**: Sees only their assigned job orders, subscriber contact info for those jobs, and inventory checked out to them +- **Client**: Sees only their own account — bills, balance, payment history, plan details, ticket submission + +### Claude's Discretion +- Session duration and refresh token strategy +- Super-admin panel location (same app vs separate URL) +- Additional super-admin metrics beyond the specified ones +- Password complexity requirements +- Login page design and layout +- Error messages and feedback patterns + + + + +## Specific Ideas + +- Multi-role is important because in small ISPs, technicians often double as collectors — they install/repair and collect payment on the same visit +- Collector scoping: can see all subscribers (useful for context) but can only act on (record payments for) their assigned zone — prevents accidental cross-zone entries +- Grace period on tenant suspension is important because ISPs have paying subscribers who need service continuity even if the ISP owner is late on their SaaS payment + + + + +## Deferred Ideas + +None — discussion stayed within phase scope + + + +--- + +*Phase: 01-foundation* +*Context gathered: 2026-03-04*