NetForge/.planning/phases/01-foundation/01-CONTEXT.md

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