Section 1
Strategic Context
El Dorado is a dead end — no open API, fully manual, vendor unresponsive. Japheth's platform has critical gaps. Any licensing deal creates long-term dependency. The decision is to build proprietary software: Client owns the IP, controls the roadmap, increases company valuation at exit.
Core principle: Client domain expertise is the competitive advantage. Claude Code writes the code. We write the rules. The billing logic documented here — every formula, every anomaly rule, every audit trail — is a moat El Dorado will never build.
Stack rationale: A unified Next.js stack is mandatory. One codebase, one language, one deployment — session consistency is preserved and cross-service hallucinations are eliminated. Claude Code performs best when the entire build lives in one context.
IP ownership: The Client retains full intellectual property rights to all custom software delivered under this engagement. Common Goodworks serves as the bridge between the Client's vision and a shipped product — no license or residual rights are retained by the Service Provider.
Section 2
Engagement Structure
A retainer-based engagement with a fixed total investment and a flexible delivery cadence.
Total Investment
$ fixed
Fixed total. Monthly retainer cadence to be determined by Client cash flow planning.
Weekly Commitment
10–12 hours · dedicated
Target Duration
~28 weeks, quality-first
Post-Launch Rate
$value/hour · locked
The engagement is structured as a monthly retainer across a duration to be finalized by the Client. The total investment is fixed regardless of the payment cadence selected. Common Goodworks commits to 10–12 dedicated hours per week toward the project, with any work performed above that range absorbed at no additional cost to the Client.
Payment cadence to be determined. Options under consideration: monthly fixed payments over number (#) of months. The Client selects the cadence that best aligns with their accounting and cash flow rhythm. Total remains unaltered.
A note on pacing: A 10–12 hour weekly commitment is intentional — it keeps Common Goodworks deeply engaged without overcommitting against quality. Quality is paramount. The 28-week timeline is an estimate, not a deadline. If a phase needs more time to meet the acceptance criteria, the timeline flexes before the quality bar does.
Post-launch partnership secured: Following acceptance of Phase 1, Common Goodworks has been retained by UtilityPro Billing at a locked consultant rate of $/hour for ongoing maintenance, bug fixes, new feature development, and onboarding of additional clients. The post-launch engagement is governed by a separate agreement.
Section 3
User Roles & Access Model
Four roles. Each has a distinct access scope, login experience, and capability set. The UPB Admin is the only role that can create domains, assign specialists, and onboard clients.
UPB Admin
Full system access
Internal UtilityPro staff. The only role that can configure the platform, assign specialists to domains, and onboard new clients.
Assign specialists to domains
Onboard and configure clients
Access all properties across clients
View full Audit_Log
Billing Specialist
Access by domain / region
UtilityPro employees. Each specialist is assigned a domain (primarily geographic, not exclusively) by a UPB Admin.
Upload bills, enter meter reads
Approve anomaly flag overrides
Run and edit pre-billing reports
Post charges to PMS (via CSV)
Client
Siloed — own properties only
Property management company user. Sees only their properties. Cannot post charges — approval only.
Review pre-billing reports
Approve or request edits
View posted charge history
Configure property details
Resident
Full portal · magic-link auth
End-user of billed services. Accesses a comprehensive portal via secure magic-link authentication — no persistent account required.
Full bill history — all cycles
Itemized charge breakdowns
PDF invoice download
Mobile-responsive access
Domain assignment flow: UPB Admin creates a named domain (e.g. "Southern California"), assigns properties to that domain, and assigns a billing specialist to that domain. The specialist sees exactly those properties. Domain reassignment is admin-only.
Resident experience: The resident role in v4 is meaningfully expanded. Previously scoped as a magic-link invoice viewer, the Phase 1 resident portal delivers a full self-service experience — bill history, itemized breakdowns, and downloadable PDFs on any device.
Section 4
Phased Development Roadmap
Two development phases following Discovery. Phase 0 delivers one complete billing cycle on one property; Phase 1 delivers full feature parity plus the Full Resident Portal.
D
Milestone-based
Led by Common Goodworks. Nine architectural decisions documented and signed off: domain model, auth provider, cloud deployment, 7 DB schemas, Audit_Log structure, Client approval flow, GitHub repo, Rent Manager API access, Japheth partnership position. No application code is written until Discovery closes.
In scope
- Domain model design confirmed
- Client approval flow defined
- Auth0 integration confirmed
- Cloud deployment architecture selected
- GitHub repo + Claude Code integration
- 7 Phase 0 DB schemas reviewed & approved
- Audit_Log structure finalized
- Rent Manager API credentials obtained
- Japheth partnership position documented
Out of scope
- Application code of any kind
- UI / UX design work
- Billing formula implementation
- Data migration planning
0
~14 weeks
The goal is a real billing cycle on a real pilot property — not a demo. All four user roles must function correctly, including the Client approval gate, before Phase 0 is considered complete. The pilot property is a RUBS-billed property identified by the Client with clean historical data available.
In scope
- Next.js scaffold — App Router, TypeScript, PostgreSQL, Auth0
- All 4 user roles with correct routing and data scoping
- UPB Admin: domain creation and specialist assignment
- Billing Specialist: domain-scoped property access
- Client: siloed login, pre-billing approval workflow
- Resident: magic-link invoice portal with PDF download
- Property + unit setup (manual)
- RUBS Formulas 1 & 2 via decimal.js
- PDF bill upload — pdfplumber extracts meter/account numbers; specialist labels each billable or non-billable
- CSV meter read upload
- Anomaly detection + specialist approval gate
- Pre-billing report with inline editing + live recalculation
- Client approval step before charges finalize
- Async PDF → email via SES (no S3)
- Audit_Log written on every action from day one
- 7 new DB tables + AWS baseline
Out of scope
- RUBS Formulas 3–8
- Submeter billing
- Full Resident Portal (Phase 1)
- PMS integration
- AMR auto-sync
- Bill caps, tiered rates
- AI-based bill extraction (Bedrock/Claude) — architecture-ready, activated when provider coverage gaps appear
- Reporting suite
1
~14 weeks
Phase 1 delivers complete billing feature parity with El Dorado plus the Full Resident Portal — a meaningful expansion beyond the original Phase 1 scope. By completion, the platform is capable of handling the full UtilityPro Billing portfolio and residents have comprehensive self-service access to their billing information.
In scope
- RUBS Formulas 3–8 (ratio occupancy, sq footage, per bed/bath, blended)
- Submeter billing — Methods A, B, C, D
- Direct Metered and Flat Fee billing types
- CAD, bill caps, vacancy toggles, proration rules
- Percentage-based fees (CARE discounts, surcharges)
- Tiered rate configuration
- Recurring charge auto-generation
- Multi-property specialist dashboard (domain-scoped)
- Void and re-bill workflow with full Audit_Log trail
- CSV charge export for manual PMS posting
- Full Resident Portal (see Section 5)
Out of scope
- AMR integration (Phase 2 — future SOW)
- PMS API sync (Phase 3 — future SOW)
- AI-based bill extraction (Bedrock/Claude) — drop-in upgrade when pdfplumber coverage gaps are identified
- AP Journal Entries module
- Reporting suite (Phase 5 — future SOW)
- Mobile native applications
Section 5
Full Resident Portal — New in v4
The Full Resident Portal is the most significant scope addition from v3 to v4. This section defines what the portal is, so there is no ambiguity at Phase 1 acceptance.
The Full Resident Portal is a resident-facing web experience that provides comprehensive self-service access to billing information. It is accessed via secure magic-link authentication — no resident account creation is required. The portal is mobile-responsive and works on any modern browser.
What the Full Resident Portal is: A resident-facing portal with full bill history across all billing cycles, itemized charge breakdowns showing how each charge was calculated (RUBS share, fees, CAD application, proration), PDF invoice downloads for any past cycle, customizable PDF invoice templates per client (logo, billing message, line-item labels), email distribution configuration per property, and mobile-responsive access on any device.
| Capability | Description |
|---|---|
| Full bill history | Every billing cycle the resident has been billed on is viewable, with clear cycle dates, amounts, and status. |
| Itemized charge breakdown | For each cycle, the resident sees exactly how their charges were calculated — the RUBS formula used, their share, applicable fees, any CAD deduction, proration adjustments. |
| PDF invoice download | Any past invoice can be downloaded as a PDF on demand. PDFs are generated fresh, not stored, consistent with the Phase 0 architecture. |
| Customizable PDF templates | Per-client PDF template configuration: logo placement, billing message text, and line-item label language. |
| Email distribution configuration | Property-level configuration of invoice email distribution — which addresses receive copies, which receive summaries. |
| Mobile-responsive | The portal works fluidly on phones, tablets, and desktops without requiring a native app. |
| Magic-link authentication | Residents authenticate via emailed magic links with configurable TTL. No password management, no account creation friction. |
What falls naturally outside this definition: Daily usage visibility (requires AMR data infrastructure, addressed in Phase 2), custom-domain white-labeling per client (infrastructure-heavy, later phase), and native mobile applications (a separate product decision).
Section 6
Technical Stack
Locked April 15, 2026. All decisions confirmed before any code is written.
| Layer | Technology | Rationale |
|---|---|---|
| Full stack | Next.js (App Router) | Single framework for UI, API routes, server-side logic. One codebase, one deployment. Preserves Claude Code session consistency. |
| Billing math | decimal.js | Precise financial arithmetic. All RUBS and submeter calculations run through decimal.js exclusively — never native JS number. |
| PDF extraction | pdfplumber (deterministic) | Extracts meter/account numbers from digital utility bill PDFs using label pattern matching. Covers known pilot providers in Phases 0–1. AWS Bedrock (Claude) is the designed-in upgrade path when new provider formats exceed pattern coverage — same extraction interface, no architectural change required. |
| PDF + email | Async → SES | PDFs generated on demand and attached to emails via AWS SES. No S3 bucket — files are transient. |
| Database | PostgreSQL (RDS) | Managed via AWS RDS. All billing tables + Audit_Log in the same instance. |
| Audit trail | Audit_Log table | Every action, edit, approval, void written to a PostgreSQL table. From day one — never retrofitted. |
| Auth | Auth0 + magic link | Handles UPB Admin, Specialist, and Client roles. Residents use magic-link tokens — no Auth0 seat required. |
| Cloud | AWS | EC2/ECS for compute, RDS, SES for email, CloudWatch for monitoring. |
| Repository | GitHub | Claude Code integrates natively. |
| Domain | app.utilityprobilling.com | App portal. www remains the marketing site. |
Section 7
Data Model Status
13-table core schema complete. Seven tables added during Discovery. Audit_Log always-on from day one.
| Category | Tables | Status |
|---|---|---|
| Core schema | Clients, Properties, Property_Groups, Units, Leases, Residents, Meters, Meter_Reads, Utility_Bills, Charges, Fees, Client_Invoicing | Done · Apr 2026 |
| Phase 0 additions | Users, Domains, Billing_Cycles, Anomaly_Approvals, Billing_Cycle_Snapshots, Documents, Property_Config | Designed in Discovery |
| Always-on | Audit_Log | Day one · never retrofitted |
Section 8
Risk Register
Key risks monitored across the engagement. Updated from v3 to reflect v4 scope and engagement structure.
High
Floating point in billing math
decimal.js for every financial calculation. Never native JS number arithmetic on money. A single float error is a billing dispute in production.
High
Audit_Log as afterthought
Must be written from day one — every action, edit, approval, void. Retrofitting produces gaps exactly where billing disputes arise.
High
Portal scope interpretation
Full Resident Portal is defined affirmatively in Section 5. Features outside that definition are not in scope and belong to future phases.
High
Client approval gate ordering
Phase 0 is not done until the Client role can log in, see siloed properties, and approve the pre-billing report. Must be built before any real billing cycle runs.
Medium
Pace vs. scope tension
10–12 hrs/week with portal added to Phase 1. Timeline may extend to ~30+ weeks. Quality is paramount over timeline; acceptable per Client.
Medium
Data provision cadence
Co-founder Zachariah provides data; any delays in historical data availability for formula validation will extend Phase 0 acceptance.
Medium
Phase 0 scope expansion
Phase 0 is deliberately narrow. Do not add formulas or portal features until the first real billing cycle completes. Real usage feedback is worth more than any planned feature.
Medium
Next.js timeout for async jobs
Long-running batch PDF jobs may exceed serverless timeouts. Plan for Lambda or background worker pattern in Phase 1.