Skip to content

IMPLEMENTATION_CHECKLIST.md

Latest commit

 

History

History
905 lines (698 loc) · 27 KB

IMPLEMENTATION_CHECKLIST.md

File metadata and controls

905 lines (698 loc) · 27 KB

Implementation Checklist

Track your progress as you build the RadBooks platform.

Last Updated: February 24, 2026 Current Phase: Phase 15 — Program Spending ✅, Campaigns, Attachments

Phase 1: Foundation ✅ (Complete!)

Project Setup

  • Create Next.js project with TypeScript
  • Install and configure Tailwind CSS
  • Set up Shadcn/ui components
  • Initialize Git repository
  • Create GitHub repository (optional)

Database Setup

  • Install and configure PostgreSQL
  • Set up Prisma
  • Create database schema (schema.prisma)
  • Generate Prisma Client
  • Push schema to database
  • Create seed script
  • Run seed script with GRIT data

Authentication

  • Sign up for Clerk (or Supabase Auth)
  • Install auth library
  • Configure auth middleware
  • Create login page
  • Create registration page
  • Test authentication flow

Project Structure

  • Create folder structure per PROJECT_STRUCTURE.md
  • Set up route groups
  • Create basic layout components
  • Configure environment variables

Development Tools

  • Set up ESLint
  • Configure Prettier
  • Install VS Code extensions (user-dependent)
  • Set up Git hooks (optional)

Milestone: Basic app runs with auth and database ✅ COMPLETE!

Phase 2: Core Ledger (Weeks 4-6)

Chart of Accounts

  • Create Account model UI components
  • Build account tree view component
  • Implement create account form (with auto-generated codes)
  • Implement edit account form
  • Add account activation/deactivation
  • Create standard account templates
  • Test hierarchical relationships

Transaction Recording

  • Design transaction form UI
  • Create transaction model types
  • Implement double-entry logic
  • Build income recording form
  • Build expense recording form
  • Add transfer between accounts
  • Implement transaction validation

Balance Calculations

  • Write balance calculation function
  • Test asset account balances
  • Test revenue account balances
  • Test expense account balances
  • Create balance caching strategy
  • Add balance recalculation triggers

Transaction List

  • Create transaction table component
  • Add pagination
  • Implement filters (date, type, account)
  • Add search functionality
  • Create transaction detail view
  • Add export to CSV

Transaction Editing & Voiding

  • Add bi-temporal versioning fields to Transaction model
  • Create balance reversal utility (reverseAccountBalances)
  • Create editTransaction service (atomic: close old version → reverse balances → create new version → apply new balances)
  • Create voidTransaction service (atomic: close version → mark voided → reverse balances)
  • Add PATCH API endpoint for editing transactions
  • Add POST API endpoint for voiding transactions
  • Update GET API to filter voided/temporal versions
  • Create EditTransactionForm component (pre-populated, requires change reason)
  • Create VoidTransactionDialog component (confirmation with required reason)
  • Update TransactionList with Edit/Void buttons, voided styling, show-voided toggle
  • Write comprehensive tests (10 service tests, balance integrity)

Milestone: Working general ledger with transaction recording

Phase 3: Organization & User Management (Weeks 7-8)

Organization Setup

  • Create organization creation form
  • Build organization settings page
  • Add logo upload
  • Add organization theming (primary/accent colors)
  • Configure fiscal year settings
  • Create organization slug/URL

User Roles

  • Implement role-based middleware
  • Create role assignment UI
  • Build org admin permissions
  • Test permission boundaries
  • Add audit logging

Organization Users

  • Create user invitation system
  • Build user management UI
  • Add role assignment form
  • Implement user removal
  • Test multi-org access

Platform Admin

  • Create platform admin dashboard
  • Build organization list view
  • Move organization routes to /org/[slug] (fix routing conflict)
  • Add organization creation (admin)
  • Create user management interface
  • Add system-wide analytics
  • Refactor platform admin to system-wide flag
    • Add isPlatformAdmin field to User model
    • Migrate existing PLATFORM_ADMIN users
    • Update authentication checks
    • Update navigation components
    • Update API routes (invitations, settings, role assignment)
    • Build verification passed

Milestone: Multi-organization support with roles ✅

Phase 4: Public Transparency Features (Weeks 9-10)

Public Dashboard Design

  • Design organization landing page
  • Create financial overview cards
  • Build responsive layout
  • Add organization branding

Financial Overview

  • Calculate current balance
  • Display total revenue (fiscal year)
  • Display total expenses (fiscal year)
  • Create fiscal year selector

Transaction Feed

  • Build public transaction list
  • Filter anonymous donor names
  • Add date range filter
  • Implement pagination
  • Create transaction categories view

Charts & Visualizations

  • Revenue vs. expense chart (monthly)
  • Fiscal year comparison chart
  • Expense breakdown by category (pie chart)
  • Revenue sources breakdown
  • Trend line (cumulative balance)

Export & Reports

  • Implement CSV export
  • Create PDF report generation (via browser print)
  • Build fiscal year summary report
  • Add expense detail report (Income Statement)
  • Generate revenue report (Income Statement)
  • Build Income Statement page with comparative periods
  • Build Balance Sheet page with comparative periods
  • Create Reports landing page
  • Create Financial Dashboard with charts (recharts)
  • Add fiscal period utilities (year/quarter/month)
  • Add period selector component (Year/Quarter/Month granularity)
  • Add Reports link to navigation (all roles - transparency-first)
  • Add comparative prior-period support to report APIs
  • Write fiscal period unit tests (18 tests)

Milestone: Public transparency dashboard live

Phase 5: Donation Processing (Weeks 11-12)

Stripe Setup

  • Create Stripe account
  • Install Stripe SDK
  • Configure Stripe keys
  • Test Stripe in test mode

Donation Form

  • Design donation page UI
  • Create donation amount selector
  • Add custom amount input
  • Implement anonymous donation toggle
  • Add donor message field

Stripe Checkout

  • Create checkout session endpoint
  • Build success page
  • Build cancellation page
  • Handle redirect flow
  • Test full donation flow

Webhook Handler

  • Create webhook endpoint
  • Implement signature verification
  • Handle checkout.session.completed
  • Record donation transaction
  • Update donor totals
  • Test webhook locally (Stripe CLI)

Manual Donations

  • Create manual donation form (admin)
  • Add Venmo payment recording
  • Add check payment recording
  • Add cash payment recording
  • Implement reference number field

Receipts

  • Design receipt template
  • Generate receipt PDF
  • Send receipt email
  • Add receipt download
  • Store receipt history

Milestone: End-to-end donation processing

Phase 6: Program Spending ✅ (Complete!)

Renamed from "Planned Purchases" to align with IRS 990 terminology

Program Spending CRUD

  • Create ProgramSpending model with bi-temporal versioning
  • Create program-spending.service.ts with CRUD + temporal versioning
  • Create API routes (GET list, POST, GET/PATCH/DELETE single)
  • Build ProgramSpendingList component with summary cards, filters, progress bars
  • Build ProgramSpendingForm component (create/edit)
  • Build ProgramSpendingDetail modal with inline editing
  • Simplified workflow: Planned → Purchased / Cancelled (no priority)
  • Create migration to rename PlannedPurchase → ProgramSpending
  • Create migration to simplify SpendingStatus enum

Multi-Transaction Linking

  • Create ProgramSpendingTransaction junction table
  • Implement linkTransaction / unlinkTransaction service functions
  • Create transaction link/unlink API routes
  • Build LinkTransactionDialog with transaction search
  • Compute actualTotal as SUM of linked transaction amounts
  • Show funding progress bars (actual vs estimated)

Image Upload & Gallery

  • Set up Vercel Blob for file storage (private access)
  • Create attachment.service.ts with upload/download/delete
  • Create attachment API routes with authenticated proxy for private blobs
  • Build ImageGallery component with thumbnail grid and lightbox viewer
  • Display image attachments as photo gallery in detail view
  • Display non-image attachments as file list

Statistics & Reporting

  • Create spending statistics API endpoint
  • Build summary cards (Total, Planned, Purchased, Budget, Actual Spent)
  • Add spending statistics to temporal analytics
  • Create getSpendingStatisticsOverTime function

Navigation & Access

  • Add Program Spending to sidebar for all roles (including DONOR)
  • Enforce ORG_ADMIN/PLATFORM_ADMIN for create/edit/delete at API level
  • Add Megaphone icon for Campaigns navigation link

Testing

  • Create service unit tests (program-spending.service.test.ts)
  • Create API contract tests (program-spending-api-contract.test.ts)
  • All 414 tests passing

Milestone: Program spending tracking complete ✅

Phase 7: Donor Features (Weeks 15-16)

Donor Profile

  • Create donor dashboard
  • Display lifetime giving total
  • Show recent donations
  • Build donation history table

Cross-Organization Tracking

  • Aggregate donations across orgs
  • Create org-specific breakdowns
  • Calculate total impact
  • Display organizations supported

Privacy Controls

  • Add anonymous donation toggle
  • Create donor highlight opt-in/out
  • Update privacy settings page
  • Retroactive privacy changes

Donor Recognition

  • Build donor highlights section
  • Create top donors list (opt-in)
  • Display recent donors
  • Add "thank you" messages

Reports & Documents

  • Generate annual giving statement
  • Create tax documentation
  • Export donation history CSV
  • Download individual receipts

Milestone: Complete donor experience

Phase 8: Polish & Testing (Weeks 17-18)

UI/UX Refinement

  • Review all pages for consistency
  • Improve loading states
  • Add skeleton loaders
  • Enhance error messages
  • Improve success feedback

Mobile Responsiveness

  • Test all pages on mobile
  • Fix mobile layout issues
  • Optimize touch targets
  • Test on different screen sizes

Performance Optimization

  • Optimize database queries
  • Add database indexes
  • Implement caching strategy
  • Optimize images
  • Code splitting
  • Run Lighthouse audit

SEO

  • Add meta tags
  • Create sitemap
  • Implement Open Graph tags
  • Add structured data (JSON-LD)
  • Test social sharing

Accessibility

  • Run accessibility audit
  • Add ARIA labels
  • Test keyboard navigation
  • Check color contrast
  • Test with screen reader

Security Audit

  • Review authentication flow
  • Check authorization rules
  • Test input validation
  • Verify CSRF protection
  • Check for XSS vulnerabilities
  • Review sensitive data handling

Testing

  • Write unit tests (>80% coverage)
  • Create integration tests
  • Build E2E test suite
  • Test edge cases
  • Perform load testing

Milestone: Production-ready application

Phase 9: Deployment (Week 19)

Pre-Deployment

  • Review environment variables
  • Set up production database (Neon)
  • Configure production Stripe account
  • Set up production auth (Clerk)
  • Test production credentials

Vercel Deployment

  • Create Vercel account
  • Connect GitHub repository
  • Configure build settings
  • Add environment variables
  • Set up custom domain (radbooks.org)

Database Migration

  • Run production migrations
  • Seed initial data
  • Test database connection
  • Set up automated backups

Monitoring

  • Set up error tracking (Sentry)
  • Configure uptime monitoring
  • Add analytics (optional)
  • Set up logging
  • Create status page

Testing in Production

  • Test registration flow
  • Make test donation
  • Record test transaction
  • Verify webhook delivery
  • Check email delivery

Documentation

  • Create user guide
  • Write admin documentation
  • Document API endpoints
  • Create FAQ
  • Write troubleshooting guide

Milestone: ✅ Live in production at radbooks.org!

Phase 10: Beta Testing (Week 20)

GRIT Onboarding

  • Create GRIT organization
  • Set up chart of accounts
  • Add board members as admins
  • Import historical transactions
  • Configure organization settings

User Training

  • Train board members on system
  • Create video tutorials
  • Provide documentation
  • Schedule Q&A session

Feedback Collection

  • Set up feedback form
  • Schedule weekly check-ins
  • Track issues and requests
  • Monitor user behavior
  • Gather testimonials

Iteration

  • Fix reported bugs
  • Improve confusing workflows
  • Add requested features
  • Optimize performance
  • Improve documentation

Marketing Materials

  • Create landing page
  • Design promotional graphics
  • Write case study (GRIT)
  • Prepare launch announcement
  • Create demo video

Milestone: Validated MVP with real users

Post-MVP: Future Enhancements

Bank Account Sync (Phase 11)

  • Sign up for Plaid
  • Implement Plaid Link
  • Build bank connection flow
  • Auto-import transactions
  • Create reconciliation UI
  • Match imported transactions
  • Handle sync errors

Budget Management (Phase 12)

  • Create budget model
  • Build budget creation UI
  • Add budget categories
  • Track budget vs. actual
  • Generate variance reports
  • Add budget alerts

Recurring Donations (Phase 13)

  • Implement Stripe subscriptions
  • Create recurring donation form
  • Build subscription management
  • Handle failed payments
  • Add donor subscription portal

Mobile App (Phase 14)

  • Choose framework (React Native/Flutter)
  • Design mobile UI
  • Implement core features
  • Add push notifications
  • Submit to app stores

QuickBooks Integration (Phase 15)

  • Sign up for QuickBooks API
  • Implement OAuth flow
  • Build sync settings
  • Map accounts to QuickBooks
  • Sync transactions
  • Handle sync conflicts

Continuous Improvements

Regular Maintenance

  • Update dependencies monthly
  • Review and fix security issues
  • Monitor error logs
  • Optimize slow queries
  • Review user feedback

Feature Requests

  • Triage incoming requests
  • Prioritize by impact
  • Create roadmap
  • Communicate timeline

Community Building

  • Share updates with users
  • Highlight success stories
  • Engage on social media
  • Build user community
  • Recognize contributors

Progress Tracking

Overall Progress

  • Phase 1 (Foundation): ✅ 100% Complete
  • Phase 2 (Core Ledger): ✅ 100% Complete
  • Phase 3 (Transparency): ✅ ~90% Complete (Org users, platform admin, logo upload, theming done)
  • Phase 4 (Public Features): ✅ Reports & exports complete
  • Phase 6 (Program Spending): ✅ 100% Complete (renamed from Planned Purchases)
  • Phase 9 (Deployment): ✅ Live at radbooks.org (Vercel + Neon)
  • Phase 11 (Temporal Architecture): ✅ 100% Complete

Recent Achievements

  • ✅ Program Spending — Full feature replacing Planned Purchases
    • Renamed model/table/enums to align with IRS 990 terminology
    • Simplified workflow: Planned → Purchased / Cancelled (removed priority)
    • Multi-transaction linking with junction table
    • Image gallery with lightbox for uploaded attachments
    • Summary cards, progress bars, statistics endpoint
    • 33 new tests (service + API contract), all 414 tests passing
  • ✅ Attachments System — Vercel Blob private store integration
    • Upload/download/delete with authenticated proxy endpoints
    • Support for TRANSACTION, BILL, PROGRAM_SPENDING entity types
    • Private blob access with Bearer token authentication
  • ✅ Campaigns Feature — Fundraising campaigns for organizations
    • Campaign CRUD with goal tracking and progress display
    • Default account configuration for automated accounting
    • Visible to all organization roles including DONOR
  • ✅ Organization Theming — Custom branding per organization
    • Logo upload via Vercel Blob (private store)
    • Primary and accent color customization
    • Theme applied to navigation and UI elements
  • ✅ Dashboard Redesign — Improved organization dashboard
    • Current assets/liabilities display instead of account counts
    • Last 30-day revenue/expenses summary
    • Recent transactions with account names (not codes)
    • Correct debit/credit arrow direction for transfers
  • ✅ Bills Improvements — UX and workflow refinements
    • Default filter to outstanding bills (excludes Paid/Cancelled)
    • Type filter changed from toggle buttons to dropdown
    • Header simplified to "Bills"
    • Bill payment transaction descriptions cleaned up

Current Focus

  • 🎯 Production: Live at radbooks.org — monitoring and stabilizing
  • Recent: Program Spending feature, Campaigns, Dashboard redesign, Bills UX
  • Next Tasks: Stripe donation processing, Donor features, GRIT Hoops onboarding

Git Branches

  • main - Production-ready code deployed to radbooks.org
  • Feature branches via PR workflow (main is protected)

What You Can Do Now

  • Visit https://radbooks.org — Production application
  • Visit /org/[slug]/reports — Financial reports (Income Statement, Balance Sheet)
  • Visit /org/[slug]/reports/dashboard — Charts and visualizations
  • Visit /org/[slug]/audit-trail — View complete change log
  • Visit /org/[slug]/time-machine — Browse historical states
  • Run tests: npm test (414 tests passing)

Last Updated: February 24, 2026

Phase 11: Temporal Data Architecture ✅ (Complete!)

Schema Design & Migration

  • Design bi-temporal versioning pattern
  • Add temporal fields to Organization model
  • Add temporal fields to Account model
  • Add temporal fields to OrganizationUser model
  • Add temporal fields to ProgramSpending model
  • Create migration with backfill logic
  • Add temporal indexes for performance
  • Apply migration to development database
  • Verify existing data migrated correctly

Utility Functions & Repository Pattern

  • Create temporal-utils.ts with query builders
  • Create MAX_DATE and MIN_DATE constants
  • Build buildCurrentVersionWhere() helper
  • Build buildAsOfDateWhere() helper
  • Create TemporalRepository generic class
  • Implement findCurrentById method
  • Implement findAllCurrent method
  • Implement findAsOf method
  • Implement findHistory method
  • Implement create method
  • Implement update method (close old, create new)
  • Implement softDelete method
  • Implement restore method

Service Layer with Versioning

  • Create organization.service.ts
  • Create account.service.ts
  • Create organization-user.service.ts
  • Create program-spending.service.ts
  • Update API routes to use services
  • Ensure all updates create versions
  • Add audit trail tracking (changedBy)
  • Test version chain integrity

Temporal Query APIs

  • Create GET /organizations/[slug]/history endpoint
  • Create GET /organizations/[slug]/as-of/[date] endpoint
  • Create GET /organizations/[slug]/changes endpoint
  • Create GET /accounts/[id]/history endpoint
  • Add query parameter validation
  • Add error handling for invalid dates
  • Test all temporal endpoints

UI Components

  • Create AsOfDatePicker component
  • Create VersionHistory component
  • Create ChangeIndicator component
  • Create VersionComparison component
  • Build /org/[slug]/audit-trail page
  • Build /org/[slug]/time-machine page
  • Add version history to account pages
  • Test UI components

Financial Reporting with Temporal Support

  • Create generateBalanceSheet(asOfDate)
  • Create generateIncomeStatement(period)
  • Create generateCashFlow(period)
  • Add balance sheet API endpoint
  • Add income statement API endpoint
  • Add cash flow API endpoint
  • Test reports with historical dates

Analytics with Change Tracking

  • Create getAccountEvolution()
  • Create getChartEvolution()
  • Create getMembershipChanges()
  • Create getPurchaseTimeline()
  • Create getOrganizationGrowthMetrics()
  • Add membership analytics endpoint
  • Test analytics functions

Testing & Validation

  • Create unit tests for temporal-utils (14 tests)
  • Create unit tests for reporting logic (20 tests)
  • Create unit tests for analytics (15 tests)
  • Create unit tests for organization service (13 tests)
  • Create unit tests for account service (15 tests)
  • Run all tests (77 tests passing)
  • Generate coverage report (94% on temporal-utils)
  • Integration tests (optional - deferred)
  • Performance tests (optional - post-deployment)

Documentation

  • Create TEMPORAL_SCHEMA_DESIGN.md
  • Update TEMPORAL_IMPLEMENTATION_STATUS.md
  • Create API_REFERENCE.md
  • Update README.md with temporal features
  • Update IMPLEMENTATION_CHECKLIST.md
  • Document query patterns and examples
  • Add migration notes

Deployment Readiness

  • All code committed to feature branch
  • All tests passing
  • Documentation complete
  • Migration script tested
  • Create Pull Request
  • Code review
  • Merge to main
  • Production deployment

Status: ✅ All phases complete - Production ready!

Phase 12: Financial Reports UI ✅ (Complete!)

Report Infrastructure

  • Create fiscal period utilities (year/quarter/month)
  • Build PeriodSelector component
  • Build ReportTable component
  • Build ExportButtons component (CSV/JSON)

Income Statement

  • Create Income Statement API with period filtering
  • Build Income Statement page with revenue/expense breakdown
  • Support year, quarter, and month granularity

Balance Sheet

  • Create Balance Sheet API with period filtering
  • Build Balance Sheet page with assets/liabilities/equity sections
  • Support year, quarter, and month granularity

Financial Dashboard

  • Build Reports landing page with navigation cards
  • Create Financial Dashboard with recharts visualizations
  • Add revenue vs expense trends chart
  • Add navigation to reports from sidebar

Phase 13: Transaction Editing ✅ (Complete!)

Bi-Temporal Versioning

  • Add temporal versioning fields to Transaction model
  • Add void/edit support fields (isVoided, voidedAt, voidReason)
  • Create migration scripts

Transaction Service

  • Create editTransaction with version chain (previousVersionId → versionId)
  • Create voidTransaction with balance reversal
  • Create getTransactionHistory to follow version chain
  • Fix P2002 unique constraint bug (don't set id on new versions)

Transaction Editing UI

  • Build EditTransactionForm component
  • Build VoidTransactionDialog component
  • Update TransactionList with edit/void actions
  • Show version status badges (Edited/Voided)

Bi-Temporal Filtering

  • Fix as-of-date filter to use system time (systemFrom/systemTo)
  • Add buildBitemporalAsOfWhere() helper to temporal-utils
  • Add default current-version filter (systemTo = MAX_DATE)
  • Add temporal context banner for historical views

Testing

  • Add P2002 regression test
  • Add version chain history tests
  • Add bi-temporal as-of-date filtering tests
  • All 288 tests passing

Phase 14: Contacts, Bills & Pledges ✅ (Complete!)

Schema & Database

  • Add Contact model with bi-temporal versioning
  • Add Bill model with status lifecycle
  • Add BillPayment join model (Bill ↔ Transaction)
  • Add ContactType, ContactRole, BillDirection, BillStatus enums
  • Add optional contactId to Transaction model
  • Create migration script

Contact Management

  • Create contact.service.ts with CRUD + temporal versioning
  • Implement findOrCreateForUser() for User ↔ Contact linking
  • Create contact API routes (GET list, POST, GET single, PATCH, DELETE)
  • Build ContactList component with search/filter
  • Build ContactForm component (create/edit)
  • Build ContactSelector autocomplete component
  • Add Contacts to org sidebar navigation

Bill Management

  • Create bill.service.ts with status lifecycle management
  • Implement status transitions (DRAFT→PENDING→PARTIAL→PAID, CANCELLED)
  • Create bill API routes (GET list, POST, GET single, PATCH)
  • Build BillList component with direction tabs and status filters
  • Build BillForm component with contact selector
  • Build BillDetail component with payment history and progress bar
  • Add Bills to org sidebar navigation

Payment Linking

  • Create bill-payment.service.ts (record, link, unlink, reverse)
  • Create payment API route (POST payment on bill → creates Transaction + BillPayment atomically)
  • Handle void: reverse BillPayments and recalculate bill status

Contact on Transactions

  • Add ContactSelector to RecordTransactionForm
  • Add ContactSelector to EditTransactionForm
  • Accept contactId in POST/PATCH transaction APIs
  • Show Contact column in TransactionList
  • Include contact data in transaction list API response

Dashboard & Reporting

  • Create aging summary API (Current/1-30/31-60/61-90/90+ buckets)
  • Build AgingSummary component (payables + receivables)
  • Build OutstandingBillsWidget dashboard component
  • Create contact transaction history API
  • Build ContactTransactionHistory component
  • Add transaction history to contact detail dialog

Ready for Phase 2: Core Ledger Implementation 🚀

Next Steps:

  1. Build account tree view component
  2. Implement transaction recording forms
  3. Create transaction list with filters
  4. Add balance calculation views

Notes

  • Mark items with [x] when completed
  • Update dates as you progress
  • Adjust timeline based on your pace
  • Don't skip testing!
  • Celebrate milestones 🎉

Need Help?

Refer back to:

Good luck building! 🚀