🧑‍💻 IBM BOB FULL-STACK DEVELOPMENT BLUEPRINT 1. 🎯 Product Requirements Product Objective Build a web-based invoice management application that allows small businesses and accountants to manage customers and invoices from a centralized dashboard. Primary Problems Manual invoice creation is time-consuming. Businesses need a central place to track invoices. Users need visibility into paid, unpaid, and overdue invoices. Invoice records should be searchable and easy to manage. Confirmed Requirements User authentication Customer management Invoice creation Invoice editing Invoice status tracking PDF invoice generation Invoice emailing Dashboard Reports Search and filtering Responsive UI Assumptions Assumption: Payment collection itself is not required in the MVP. Assumption: Users can access only data belonging to their organization. Assumption: Email sending is handled through an external email provider. Assumption: REST APIs will connect frontend and backend. MVP Scope 1. Authentication 2. Dashboard 3. Customer management 4. Invoice management 5. PDF generation 6. Email delivery 7. Invoice status tracking 8. Basic reporting Future Scope Online payments Recurring invoices Automated payment reminders Multi-currency support Advanced analytics Accounting integrations --- 2. 👥 User & Role Model Business Owner Permissions: Manage organization data Create/edit/delete customers Create/edit/delete invoices View reports Send invoices Manage users Accountant Permissions: View customers Create invoices Edit invoices Send invoices View reports The accountant should not automatically receive organization-administration permissions. Authorization Rule Every customer and invoice request must verify that the requested resource belongs to the authenticated user's organization. --- 3. 🧭 User Journey Map Workflow A: Login Entry: Login page → User enters email/password → Frontend validates input → Backend authenticates user → Session/token is established → User is redirected to dashboard Failure: Invalid credentials → generic authentication error Server failure → retry message Missing fields → client-side validation --- Workflow B: Create Customer Dashboard → Customers → Add Customer → Enter customer details → Validate form → POST customer API → Database stores customer → UI refreshes customer list Failure: Invalid email → validation error Missing name → validation error Duplicate customer → appropriate business-rule error Database failure → generic server error --- Workflow C: Create Invoice Dashboard → Invoices → Create Invoice → Select customer → Add invoice items → Calculate totals → Validate invoice → Save invoice → Generate PDF → Display invoice details --- Workflow D: Send Invoice Invoice details → Click Send → Backend verifies invoice ownership → Generate/retrieve PDF → Email service sends invoice → Invoice delivery status recorded → UI displays result If email delivery fails, the invoice itself should remain saved. --- 4. 🏗️ System Architecture User | v React Frontend | | HTTPS / REST API v Node.js Backend | +---- Authentication | +---- Authorization | +---- Invoice Service | +---- Customer Service | +---- Report Service | +---- Email Service | +---- PDF Service | v PostgreSQL Database Request Flow 1. User interacts with React. 2. React sends authenticated API request. 3. Backend validates authentication. 4. Authorization verifies organization/resource access. 5. Request validation runs. 6. Business service processes operation. 7. Database operation executes. 8. Backend returns structured response. 9. Frontend updates the relevant UI state. --- 5. 🎨 Frontend Architecture Pages Login Dashboard Customers Customer Details Create Invoice Invoice List Invoice Details Reports Settings Components Sidebar Header DataTable InvoiceForm CustomerForm StatusBadge SearchBar FilterPanel Modal Toast LoadingState EmptyState ErrorState State Separate: Authentication state Server/API state Form state UI state Avoid putting all application state into one global store. Form Validation Validate: Required fields Email format Invoice dates Invoice item quantity Prices Customer selection Backend validation must remain authoritative even if frontend validation passes. --- 6. ⚙️ Backend Architecture Suggested module structure: backend/ auth/ users/ organizations/ customers/ invoices/ reports/ email/ pdf/ middleware/ validation/ database/ errors/ Layering Route ↓ Controller ↓ Validation ↓ Authorization ↓ Service ↓ Repository/Database Business rules should remain in services rather than React components or route handlers. --- 7. 🗄️ Database Schema users id organization_id name email password_hash role created_at updated_at organizations id name created_at updated_at customers id organization_id name email phone address created_at updated_at invoices id organization_id customer_id invoice_number issue_date due_date subtotal tax total status created_at updated_at invoice_items id invoice_id description quantity unit_price total invoice_deliveries id invoice_id recipient_email status sent_at failure_reason Relationships Organization | +---- Users | +---- Customers | +---- Invoices | +---- Invoice Items | +---- Invoice Deliveries Important Constraints Invoice number unique within organization. Invoice item must belong to its invoice. Invoice must belong to the same organization as its customer. Required monetary values must be valid. Foreign keys must enforce relationships. Indexes Consider indexes on: organization_id customer_id invoice_number status due_date created_at --- 8. 🔌 API Contract Map Method Route Purpose Auth POST /auth/login Login No POST /auth/logout Logout Yes GET /customers List customers Yes POST /customers Create customer Yes GET /customers/:id Customer details Yes PATCH /customers/:id Update customer Yes DELETE /customers/:id Delete customer Yes GET /invoices List invoices Yes POST /invoices Create invoice Yes GET /invoices/:id Invoice details Yes PATCH /invoices/:id Update invoice Yes DELETE /invoices/:id Delete invoice Yes POST /invoices/:id/send Send invoice Yes GET /reports/invoices Invoice report Yes Example Create Invoice Request { "customerId": "customer-id", "issueDate": "2026-09-10", "dueDate": "2026-10-10", "items": [ { "description": "Consulting", "quantity": 2, "unitPrice": 500 } ], "tax": 100 } Success Response { "id": "invoice-id", "invoiceNumber": "INV-001", "status": "unpaid", "total": 1100 } Error Format Use one consistent structure: { "error": { "code": "VALIDATION_ERROR", "message": "Invalid invoice data", "fields": { "dueDate": "Due date must be after issue date" } } } --- 9. 🔐 Authentication & Authorization Authentication Use secure password hashing and server-managed authentication/session mechanisms appropriate to the chosen deployment architecture. Never store plaintext passwords. Authorization Every protected operation should verify: Authenticated? ↓ User active? ↓ Correct organization? ↓ Required role? ↓ Resource ownership? ↓ Allow operation Sensitive Operations Require authorization checks for: Invoice deletion Customer deletion User management Organization settings Do not rely only on frontend route protection. --- 10. 🛡️ Security Requirements IBM Bob must implement: Server-side input validation Parameterized database queries/ORM protections Output encoding where appropriate XSS protections CSRF protection where applicable Secure authentication Authorization on every protected resource Rate limiting on authentication endpoints Secure HTTP configuration Secret management through environment/configuration Safe PDF/file handling Dependency vulnerability checks Production error sanitization Critical Rule Never generate: API_KEY = "actual-secret" Instead use environment/secret-management mechanisms. --- 11. 🧪 Testing Strategy Unit Tests Test: Invoice total calculation Tax calculation Invoice status logic Validation functions Authorization helpers API Tests Test: Login Customer creation Invoice creation Invoice retrieval Invoice updates Invoice deletion Invoice sending Authorization Tests Verify: User cannot access another organization's customer. User cannot access another organization's invoice. Accountant cannot perform owner-only operations. E2E Test Critical workflow: Login ↓ Create Customer ↓ Create Invoice ↓ View Invoice ↓ Send Invoice ↓ Verify Delivery Status Failure Tests Test: Invalid login Missing required fields Invalid dates Invalid invoice items Unauthorized resource access Database failure Email-service failure Duplicate requests --- 12. 🤖 IBM Bob Implementation Workflow Stage 1 — Project Foundation Objective: Establish the repository and application structure. Affected areas: Frontend Backend Configuration Environment configuration Testing framework Verification: Frontend starts Backend starts Type checking succeeds Tests execute No secrets committed Human checkpoint: Approve foundation before feature development. --- Stage 2 — Database Create: Organizations Users Customers Invoices Invoice items Delivery records Verification: Migration succeeds Constraints work Relationships work Seed/test data works --- Stage 3 — Backend Implement: Authentication Customer service Invoice service Authorization Validation Error handling Checkpoint: API tests must pass before frontend integration. --- Stage 4 — API Layer Implement endpoints according to the approved contracts. IBM Bob must not silently change: Routes Request structures Response structures Authentication requirements without updating the architecture and tests. --- Stage 5 — Frontend Build: Application shell Authentication pages Dashboard Customer screens Invoice screens Reports Each screen should consume the defined API rather than duplicate backend business logic. --- Stage 6 — Integrations Implement: PDF generation Email delivery External-service failures must not corrupt invoice records. --- Stage 7 — Testing Run: Unit tests API tests Component tests E2E tests Security tests --- Stage 8 — Security Hardening Review: Authentication Authorization Validation Secrets Rate limiting Dependencies Error leakage File handling --- Stage 9 — Deployment Preparation Configure: Environment variables Database migrations Build process Health checks Logging Monitoring Rollback process --- 13. 🔍 Verification Checkpoints After every IBM Bob implementation task: 1. Compare implementation against requirements. 2. Review changed files. 3. Run type checking. 4. Run build. 5. Run relevant tests. 6. Validate API contracts. 7. Check authorization. 8. Check security implications. 9. Run regression tests. 10. Confirm no unrelated files/features changed. Scope-Creep Rule If IBM Bob starts implementing: Payment processing Recurring billing Accounting integrations Advanced analytics without those features being approved, stop the implementation and request scope confirmation. --- 14. 🚀 Deployment Architecture Development ↓ Testing ↓ Staging ↓ Production Development Local frontend + backend + development database. Staging Production-like configuration for final verification. Production HTTPS Secure environment variables Production database Database backups Structured logging Monitoring Health checks Deployment Sequence 1. Run tests. 2. Build application. 3. Validate environment configuration. 4. Apply compatible database migration. 5. Deploy backend. 6. Deploy frontend. 7. Run health checks. 8. Run smoke tests. 9. Monitor logs/metrics. Rollback Maintain a deployment strategy capable of returning the application to the previous known-good version. Database migrations must be designed with application compatibility in mind. --- 15. 📊 Performance & Scalability Plan Initial Optimization Paginate invoice/customer lists. Index frequently queried fields. Avoid unnecessary database queries. Lazy-load large frontend sections. Generate PDFs efficiently. Avoid loading entire datasets into the browser. Future Scaling If usage grows: Frontend ↓ Load Balancer ↓ Multiple Backend Instances ↓ PostgreSQL + Caching + Background Workers Email delivery and heavy PDF processing can later move to background jobs if they become latency bottlenecks. Do not introduce queues, microservices, or distributed infrastructure before actual requirements justify them. --- 16. ✅ Production Readiness Roadmap P0 - Must Complete Before Production Authentication Authorization Database constraints Server-side validation Secure secrets Error handling Critical API tests E2E critical workflow HTTPS Database backup strategy Logging Health checks P1 - Strongly Recommended Rate limiting Dependency scanning Monitoring alerts Performance testing Audit logging Improved reporting P2 - Future Online payments Recurring invoices Automated reminders Accounting integrations Advanced analytics --- FINAL IBM BOB ARCHITECTURE AUDIT Area Status Product requirements ✅ Covered User workflows ✅ Covered Frontend/backend consistency ✅ Mapped Database/API consistency ✅ Mapped Authentication ✅ Defined Authorization ✅ Defined Security ✅ Defined Testing ✅ Defined Error handling ✅ Defined Deployment ✅ Defined Scalability ✅ Defined AI-agent verification ✅ Defined Scope control ✅ Defined IBM Bob Operating Rule IBM Bob should implement the application incrementally, verify each stage, and stop when a change conflicts with the approved architecture, API contract, security model, database model, or MVP scope. Result: This sample demonstrates how the prompt converts a short application idea into an end-to-end implementation plan rather than immediately generating disconnected code.