​

System Requirements Specification

​

Personal Budget Management & Enforcement System

​

1. INTRODUCTION

​

1.1 Purpose

​

1.2 Scope

• Automated transaction ingestion from Starling Bank
• Real-time budget tracking and categorization
• Threshold-based alerting and enforcement
• Historical analysis and forecasting
• Interactive dashboards and reporting

​

1.3 Definitions and Acronyms

• SRS: System Requirements Specification
• API: Application Programming Interface
• VTM: Verification Traceability Matrix
• RBAC: Role-Based Access Control
• SLA: Service Level Agreement

​

2. OVERALL DESCRIPTION

​

2.1 Product Perspective

• Data Layer: Starling Bank API (external)
• Processing Layer: N8N workflow engine
• Storage Layer: Airtable database
• Presentation Layer: Airtable interfaces & external dashboards

​

2.2 Product Functions

• Real-time transaction synchronization
• Automated categorization and tagging
• Budget allocation and tracking
• Alert generation and notification
• Spending enforcement controls
• Historical reporting and analysis

​

2.3 User Characteristics

• API integration and authentication
• Workflow automation platforms
• Database design and formulas
• Basic scripting/coding

​

2.4 Constraints

• Starling Bank API rate limits (typically 300 requests/5 minutes)
• N8N execution limits based on hosting plan
• Airtable record limits (50,000 records on Pro plan)
• Real-time webhook delivery dependencies

​

3. SYSTEM REQUIREMENTS

​

3.1 FUNCTIONAL REQUIREMENTS

​

FR-001: Transaction Ingestion

• FR-001.1: System shall authenticate with Starling Bank OAuth 2.0
• FR-001.2: System shall poll for new transactions every 5 minutes
• FR-001.3: System shall support webhook-based real-time transaction capture
• FR-001.4: System shall handle pagination for bulk historical imports
• FR-001.5: System shall deduplicate transactions based on transactionUID
• FR-001.6: System shall retrieve transaction metadata (merchant, category, location)
• FR-001.7: System shall handle failed API calls with exponential backoff retry (max 3 attempts)

​

FR-002: Transaction Storage

• FR-002.1: System shall create transaction records with fields: ID, Date, Amount, Merchant, Category, Status, Notes
• FR-002.2: System shall link transactions to budget categories
• FR-002.3: System shall maintain transaction immutability (no modifications to historical data)
• FR-002.4: System shall timestamp record creation and updates
• FR-002.5: System shall handle currency conversion for non-GBP transactions
• FR-002.6: System shall store raw API response for audit trail

​

FR-003: Budget Configuration

• FR-003.1: System shall support budget categories (Groceries, Transport, Entertainment, Bills, Discretionary, Savings)
• FR-003.2: System shall define monthly spending limits per category
• FR-003.3: System shall support rollover of unused budget to next period (optional toggle)
• FR-003.4: System shall define budget periods (monthly, quarterly, annual)
• FR-003.5: System shall calculate buffer percentages per category (default 10-15%)
• FR-003.6: System shall support subcategories with inherited parent limits

​

FR-004: Automated Categorization

• FR-004.1: System shall use merchant name matching rules
• FR-004.2: System shall use Starling’s native category codes as fallback
• FR-004.3: System shall support manual categorization rules (keyword matching)
• FR-004.4: System shall learn from manual corrections (rule suggestion)
• FR-004.5: System shall flag uncategorized transactions for review
• FR-004.6: System shall support split transactions across multiple categories

​

FR-005: Real-Time Budget Tracking

• FR-005.1: System shall calculate total spent per category for current period
• FR-005.2: System shall calculate remaining budget per category
• FR-005.3: System shall calculate percentage consumed (spent/limit * 100)
• FR-005.4: System shall identify budget status (healthy, warning, exceeded)
• FR-005.5: System shall project end-of-period spending based on current rate
• FR-005.6: System shall update calculations within 60 seconds of new transaction

​

FR-006: Threshold Alerting

• FR-006.1: System shall trigger warning alert at 80% of category budget
• FR-006.2: System shall trigger critical alert at 100% of category budget
• FR-006.3: System shall trigger daily summary at 120% of category budget
• FR-006.4: System shall support custom threshold percentages per category
• FR-006.5: System shall prevent duplicate alerts within 24-hour period
• FR-006.6: System shall include context in alerts (current spend, limit, transactions)

​

FR-007: Notification Delivery

• FR-007.1: System shall send email notifications via configured SMTP
• FR-007.2: System shall send Slack messages to specified channel/DM
• FR-007.3: System shall send SMS via Twilio (optional)
• FR-007.4: System shall support push notifications via mobile app integration
• FR-007.5: System shall allow notification preference configuration per alert type
• FR-007.6: System shall log all notification attempts and delivery status

​

FR-008: Spending Enforcement

• FR-008.1: System shall integrate with Starling Card Controls API
• FR-008.2: System shall support manual card freeze trigger
• FR-008.3: System shall support automated card freeze at configurable threshold
• FR-008.4: System shall provide manual override mechanism for emergencies
• FR-008.5: System shall log all enforcement actions with timestamps
• FR-008.6: System shall send confirmation notifications on enforcement actions

​

FR-009: Historical Analysis

• FR-009.1: System shall import 6 months of historical transactions for baseline
• FR-009.2: System shall calculate average monthly spending per category
• FR-009.3: System shall identify spending trends (increasing, stable, decreasing)
• FR-009.4: System shall detect spending anomalies (>2 standard deviations)
• FR-009.5: System shall compare current period to historical averages
• FR-009.6: System shall support custom date range analysis

​

FR-010: Starling Spaces Integration

• FR-010.1: System shall retrieve list of Spaces via API
• FR-010.2: System shall automatically transfer funds to category Spaces at period start
• FR-010.3: System shall map budget categories to corresponding Spaces
• FR-010.4: System shall reconcile Space balances with budget tracking
• FR-010.5: System shall handle Space transaction attribution

​

FR-011: Dashboard and Reporting

• FR-011.1: System shall display current budget status (traffic light indicators)
• FR-011.2: System shall show spending trends over time (charts)
• FR-011.3: System shall display top merchants by spending
• FR-011.4: System shall show category breakdown (pie/bar charts)
• FR-011.5: System shall display daily spending rate vs. budget burn rate
• FR-011.6: System shall support mobile-responsive interface design
• FR-011.7: System shall export reports in CSV/PDF formats

​

FR-012: Data Management

• FR-012.1: System shall archive transactions older than 24 months
• FR-012.2: System shall support manual transaction editing with audit trail
• FR-012.3: System shall support bulk transaction operations (categorization, deletion)
• FR-012.4: System shall provide data export functionality (full backup)
• FR-012.5: System shall support data import from external sources (CSV)
• FR-012.6: System shall maintain referential integrity across linked tables

​

3.2 NON-FUNCTIONAL REQUIREMENTS

​

NFR-001: Performance

• NFR-001.1: API polling cycle shall complete within <30 seconds
• NFR-001.2: Webhook processing shall complete within <10 seconds
• NFR-001.3: Dashboard shall load within <3 seconds
• NFR-001.4: Budget calculations shall complete within <5 seconds
• NFR-001.5: Historical import of 1000 transactions shall complete within <5 minutes

​

NFR-002: Reliability

• NFR-002.1: System shall achieve 99.5% uptime (excluding planned maintenance)
• NFR-002.2: Transaction ingestion shall have 99.9% success rate
• NFR-002.3: Alert delivery shall have 99% success rate within 2 minutes
• NFR-002.4: System shall recover automatically from transient failures
• NFR-002.5: System shall maintain data integrity during failures

​

NFR-003: Security

• NFR-003.1: System shall store API credentials encrypted at rest
• NFR-003.2: System shall use OAuth 2.0 for Starling Bank authentication
• NFR-003.3: System shall rotate access tokens before expiration
• NFR-003.4: System shall log all access to sensitive data
• NFR-003.5: System shall support 2FA for Airtable access
• NFR-003.6: System shall comply with PSD2 regulations for financial data

​

NFR-004: Scalability

• NFR-004.1: System shall support up to 500 transactions per month
• NFR-004.2: System shall support up to 20 budget categories
• NFR-004.3: System shall maintain performance with 24 months of data
• NFR-004.4: System shall support multiple Starling accounts (future)

​

NFR-005: Maintainability

• NFR-005.1: N8N workflows shall be documented with inline descriptions
• NFR-005.2: Airtable formulas shall include comments
• NFR-005.3: System shall use consistent naming conventions
• NFR-005.4: Configuration shall be externalized (no hardcoded values)
• NFR-005.5: System shall provide logging for debugging

​

NFR-006: Usability

• NFR-006.1: Dashboard shall be intuitive without training
• NFR-006.2: Configuration changes shall take effect within 1 minute
• NFR-006.3: Error messages shall be clear and actionable
• NFR-006.4: System shall support mobile access via Airtable app

​

NFR-007: Compatibility

• NFR-007.1: System shall work with Starling Bank API v2
• NFR-007.2: System shall work with N8N version 1.0+
• NFR-007.3: System shall work with Airtable REST API v0
• NFR-007.4: System shall support modern web browsers (Chrome, Firefox, Safari, Edge)

​

4. SYSTEM ARCHITECTURE

​

4.1 Component Overview

┌─────────────────────────────────────────────────────────────┐
│                        USER INTERFACE                        │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐│
│  │ Airtable Web   │  │ Airtable Mobile│  │ Email/Slack    ││
│  │ Interface      │  │ App            │  │ Notifications  ││
│  └────────────────┘  └────────────────┘  └────────────────┘│
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     PRESENTATION LAYER                       │
│  ┌────────────────────────────────────────────────────────┐ │
│  │              Airtable Interfaces & Views                │ │
│  │  • Budget Dashboard  • Transaction List  • Reports      │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       DATA LAYER                             │
│  ┌────────────────────────────────────────────────────────┐ │
│  │                   Airtable Base                         │ │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │ │
│  │  │Transactions  │  │Budget        │  │Spending      │ │ │
│  │  │Table         │  │Categories    │  │Periods       │ │ │
│  │  │              │  │Table         │  │Table         │ │ │
│  │  └──────────────┘  └──────────────┘  └──────────────┘ │ │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │ │
│  │  │Categorization│  │Alert         │  │Enforcement   │ │ │
│  │  │Rules         │  │History       │  │Log           │ │ │
│  │  │Table         │  │Table         │  │Table         │ │ │
│  │  └──────────────┘  └──────────────┘  └──────────────┘ │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    PROCESSING LAYER                          │
│  ┌────────────────────────────────────────────────────────┐ │
│  │                  N8N Workflow Engine                    │ │
│  │  ┌──────────────────────────────────────────────────┐  │ │
│  │  │  WF-001: Transaction Polling (5 min schedule)    │  │ │
│  │  │  WF-002: Webhook Transaction Capture (real-time) │  │ │
│  │  │  WF-003: Transaction Categorization             │  │ │
│  │  │  WF-004: Budget Calculation (on transaction)     │  │ │
│  │  │  WF-005: Alert Evaluation (on calculation)       │  │ │
│  │  │  WF-006: Notification Dispatch                   │  │ │
│  │  │  WF-007: Enforcement Actions                     │  │ │
│  │  │  WF-008: Historical Import (manual trigger)      │  │ │
│  │  │  WF-009: Period Rollover (daily at midnight)     │  │ │
│  │  │  WF-010: Spaces Sync (weekly)                    │  │ │
│  │  └──────────────────────────────────────────────────┘  │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    EXTERNAL SERVICES                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ Starling Bank│  │ Email Service│  │ Slack API    │      │
│  │ API          │  │ (SMTP)       │  │              │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘

​

4.2 Data Flow

1. Starling Bank → N8N (WF-001 polling or WF-002 webhook)
2. N8N → Airtable Transactions Table (create record)
3. Airtable → N8N (webhook on new record)
4. N8N (WF-003) → Apply categorization rules
5. N8N (WF-004) → Calculate budget status
6. N8N (WF-005) → Evaluate alert conditions
7. N8N (WF-006) → Send notifications if triggered
8. User → Airtable Interface (view dashboard)

​

5. DATA SCHEMA

​

5.1 Airtable Base Structure

​

Table: Transactions

​

Table: Budget Categories

​

Table: Spending Periods

​

Table: Category Performance (Linked)

​

Table: Categorization Rules

​

Table: Alert History

​

Table: Enforcement Log

​

6. N8N WORKFLOW SPECIFICATIONS

​

WF-001: Transaction Polling

1. Schedule Trigger - Cron: */5 * * * *
2. HTTP Request - Get Transactions
   • Method: GET
   • URL: https://api.starlingbank.com/api/v2/feed/account/{accountUid}/category/{categoryUid}
   • Auth: OAuth2 (bearer token)
   • Headers: Accept: application/json
   • Query Params: changesSince=
3. Check for New Transactions (IF node)
   • Condition: \{\{$json.feedItems.length\}\} > 0
4. Get Last Synced Timestamp (Airtable Read)
   • Base: Budget Tracker
   • Table: System Config
   • Filter: Field=LastSyncTimestamp
5. Loop Through Transactions (Split in Batches)
   • Batch Size: 10
6. Check if Transaction Exists (Airtable Search)
   • Filter: TransactionID = {{$json.feedItemUid}}
7. Skip if Exists (IF node)
8. Create Transaction Record (Airtable Create)
   • Map fields from API response
9. Update Last Sync Timestamp (Airtable Update)
   • Set to current timestamp
10. Error Handler (On workflow error)
    • Log to error table
    • Send notification

• Retry failed API calls 3 times with exponential backoff (5s, 15s, 45s)
• Log all errors to Airtable error log
• Send alert after 3 consecutive failures

​

WF-002: Webhook Transaction Capture

1. Webhook Trigger
   • Path: /starling-webhook
   • Method: POST
   • Response: 200 OK immediately
2. Validate Webhook Signature (Function node)
   • Verify HMAC signature
3. Parse Transaction Data (Set node)
4. Check Duplicate (Airtable Search)
5. Create Transaction Record (Airtable Create)
6. Trigger Categorization (Call WF-003)

​

WF-003: Transaction Categorization

1. Webhook Trigger (from Airtable)
2. Get Transaction Details (Airtable Read)
3. Get Categorization Rules (Airtable List)
   • Filter: Active = true
   • Sort: Priority DESC
4. Loop Through Rules (Split in Batches)
5. Apply Rule Logic (Function node)
   • Match merchant name
   • Match keywords in description
   • Match amount ranges
6. First Match Wins (IF node)
7. Update Transaction (Airtable Update)
   • Set Category
   • Set Auto Categorized = true
   • Set Categorization Rule
8. Increment Rule Usage (Airtable Update)
9. Trigger Budget Calculation (Call WF-004)
10. Flag for Manual Review (if no match)

​

WF-004: Budget Calculation

1. Webhook Trigger
2. Get Current Period (Airtable Read)
   • Filter: Status = current
3. Get Transaction Category (Airtable Read)
4. Get Category Performance Record (Airtable Search)
   • Filter: Period + Category match
5. Calculate Metrics (Function node)
   Copy

   // Total Spent (from rollup)
   const spent = $json.totalSpent;
   const limit = $json.budgetLimit;
   const remaining = limit - spent;
   const percentageUsed = (spent / limit) * 100;
   
   // Projected end-of-period spend
   const daysInPeriod = dateDiff(periodEnd, periodStart);
   const daysElapsed = dateDiff(today, periodStart);
   const daysRemaining = dateDiff(periodEnd, today);
   const dailyBurnRate = spent / daysElapsed;
   const projectedSpend = spent + (dailyBurnRate * daysRemaining);
   
   // Status
   let status;
   if (percentageUsed < 80) status = 'healthy';
   else if (percentageUsed < 100) status = 'warning';
   else status = 'exceeded';
   
   return {
     spent, limit, remaining, percentageUsed,
     projectedSpend, dailyBurnRate, status
   };
   
6. Update Performance Record (Airtable Update)
7. Trigger Alert Evaluation (Call WF-005)

​

WF-005: Alert Evaluation

1. Receive Budget Metrics (input)
2. Get Alert History (Airtable Read)
   • Filter: Category + Period + Last 24h
3. Check 80% Threshold (IF node)
   • Condition: percentageUsed >= 80 AND no recent 80% alert
4. Check 100% Threshold (IF node)
   • Condition: percentageUsed >= 100 AND no recent 100% alert
5. Check 120% Daily Threshold (IF node)
   • Condition: percentageUsed >= 120 (daily check at 8pm)
6. Create Alert Record (Airtable Create)
7. Format Alert Message (Function node)
   Copy

   const alertMessages = {
     warning: `⚠️ Budget Warning: ${category}
     You've spent £${spent} (${percentageUsed}%) of your £${limit} budget.
     £${remaining} remaining for the rest of the period.`,
     
     critical: `🚨 Budget EXCEEDED: ${category}
     You've spent £${spent} (${percentageUsed}%) of your £${limit} budget.
     You're £${Math.abs(remaining)} over budget.`,
     
     daily: `📊 Daily Budget Update: ${category}
     Spent: £${spent} / £${limit} (${percentageUsed}%)
     Daily burn rate: £${dailyBurnRate}
     Projected month-end: £${projectedSpend}`
   };
   
8. Trigger Notification (Call WF-006)
9. Trigger Enforcement (Call WF-007 if applicable)

​

WF-006: Notification Dispatch

1. Receive Alert Data (input)
2. Get User Notification Preferences (Airtable Read)
3. Send Email (Email node - if enabled)
   • SMTP Configuration
   • To: user email
   • Subject: Alert type + category
   • Body: formatted message (HTML)
4. Send Slack (Slack node - if enabled)
   • Workspace: configured workspace
   • Channel: #budget-alerts or DM
   • Message: formatted message (Slack markdown)
   • Attachments: budget chart image
5. Send SMS (Twilio node - if enabled)
   • To: user phone
   • Message: shortened alert message
6. Update Alert Record (Airtable Update)
   • Set delivery status
   • Set channels used

​

WF-007: Enforcement Actions

1. Receive Enforcement Request (input)
2. Check Enforcement Policy (Airtable Read)
   • Get category enforcement settings
3. Evaluate Override (IF node)
   • Check for emergency override code
4. Call Starling Card Controls API (HTTP Request)
   • Method: PUT
   • URL: https://api.starlingbank.com/api/v2/card/{cardUid}/controls
   • Body: { "enabled": false } for freeze
5. Create Enforcement Log (Airtable Create)
6. Send Confirmation Notification (Call WF-006)
7. Schedule Auto-Unfreeze (if temporary)
   • Create scheduled workflow trigger

​

WF-008: Historical Import

1. Manual Trigger (button)
2. Get Import Parameters (input form)
   • Start date (default: 6 months ago)
   • End date (default: today)
3. Call Starling API (HTTP Request)
   • Paginated requests for date range
4. Process in Batches (Split in Batches - 100 records)
5. Create Transaction Records (Airtable Create)
6. Trigger Categorization (Call WF-003 for each batch)
7. Generate Import Summary (Function node)
8. Send Completion Notification

​

WF-009: Period Rollover

1. Schedule Trigger (Cron: 0 0 * * *)
2. Check Period End (Function node)
   • Is today the last day of current period?
3. Close Current Period (Airtable Update)
   • Set status = closed
   • Calculate final metrics
4. Create New Period (Airtable Create)
   • Start date = tomorrow
   • End date = end of next period
   • Status = current
5. Handle Rollover Budgets (Function + Airtable Update)
   • For categories with rollover enabled
   • Add unused budget to next period limit
6. Reset Category Performance (Airtable Create)
   • New records for new period
7. Send Period Summary Report (Call WF-006)
   • Summary of closed period
   • Spending highlights
   • Budget performance

​

WF-010: Spaces Synchronization

1. Schedule Trigger (Cron: 0 9 * * 0)
2. Get Starling Spaces (HTTP Request)
   • URL: https://api.starlingbank.com/api/v2/account/{accountUid}/spaces
3. Get Budget Categories (Airtable List)
   • Filter: Starling Space ID is not empty
4. Match Categories to Spaces (Function node)
5. Calculate Target Balances (Function node)
   • Based on remaining budget
6. Transfer Funds (HTTP Request - for each mismatch)
   • URL: https://api.starlingbank.com/api/v2/account/{accountUid}/spaces/{spaceUid}/add-money
   • OR withdraw if over-funded
7. Log Transfers (Airtable Create)
8. Send Sync Summary

​

7. DASHBOARD SPECIFICATIONS

​

7.1 Main Budget Dashboard

• Total Budget This Period: £X,XXX
• Total Spent: £X,XXX (XX%)
• Remaining: £X,XXX
• Status: Healthy/Warning/Critical (color coded)

• Category name with icon
• Progress bar (spent/limit)
• Spent: £XXX / £XXX
• Remaining: £XXX
• Status indicator (🟢🟡🔴)
• “View Details” button

• Line chart showing daily spending
• Comparison to previous period
• Budget burn rate line
• Projected end-of-period spend

• Last 10 transactions
• Columns: Date, Merchant, Amount, Category, Status
• Quick categorization action for uncategorized
• “View All” button

• Bar chart of top 10 merchants by spend
• Clickable to filter transactions

• Recent alerts list
• Quick action buttons:
  • View all alerts
  • Freeze cards
  • Export report
  • Adjust budgets

• Desktop: 3-column layout
• Tablet: 2-column layout
• Mobile: Single column stack

​

7.2 Category Detail View

• Category name, icon, and color
• Budget limit (editable)
• Current period dates

• Total spent with large number
• Percentage gauge (circular progress)
• Remaining budget
• Daily burn rate
• Projected month-end spend
• Days remaining

• All transactions for this category in current period
• Sortable by date, amount
• Filterable by merchant, date range
• Bulk categorization actions

• Compare current period to last 3 periods
• Bar chart showing monthly spend trend
• Average, min, max indicators

• Pie chart of spending by merchant
• Table with merchant totals

​

7.3 Transaction Management View

• Date range picker
• Category multi-select
• Merchant search
• Amount range slider
• Status filter
• Payment method filter

• All fields visible
• Inline editing for category, notes
• Bulk selection and actions
• Sort by any column
• Search across all fields

• Export selected (CSV)
• Bulk categorize
• Delete selected
• Create categorization rule from selected

​

7.4 Budget Configuration View

• List of all categories
• Add/edit/delete categories
• Set limits
• Configure buffer percentages
• Enable/disable rollover
• Link to Starling Spaces

• List of all rules
• Add/edit/delete rules
• Test rule against historical transactions
• Enable/disable rules
• Priority ordering (drag and drop)

• Configure threshold percentages
• Enable/disable notification channels
• Set notification frequency
• Configure quiet hours

• Enable/disable automatic card freeze
• Set freeze thresholds by category
• Configure emergency override codes
• Set auto-unfreeze schedules

​

7.5 Reporting & Analytics View

• Select multiple periods
• Side-by-side comparison
• Key metrics: total spent, budget adherence, top categories
• Trend analysis

• Anomaly detection highlights
• Recurring transaction identification
• Seasonal pattern analysis
• Spend forecasting

• Monthly summary report (PDF)
• Transaction export (CSV)
• Budget vs. actual report
• Category performance report

​

8. VERIFICATION TRACEABILITY MATRIX (VTM)

​

8.1 Test Suite Overview

​

8.2 Detailed Verification Traceability Matrix

​

9. TEST SPECIFICATIONS

​

9.1 Test Suite TS-001: API Integration Tests

​

TC-001.1: OAuth 2.0 Authentication

• Valid Starling developer credentials
• Redirect URL configured Steps:

1. Initiate OAuth authorization request
2. Provide user credentials
3. Capture authorization code
4. Exchange code for access token
5. Verify token validity Expected Results:

• Access token received
• Token includes required scopes
• Token can be used for API calls Pass Criteria: Valid access token obtained

​

TC-001.2: Transaction Polling Schedule

• N8N workflow WF-001 active
• Logging enabled Steps:

1. Monitor workflow executions for 30 minutes
2. Record execution timestamps
3. Calculate intervals Expected Results:

• 6 executions in 30 minutes
• Intervals are 5 minutes ±10 seconds Pass Criteria: All intervals within tolerance

​

TC-001.3: Webhook Real-Time Capture

• Webhook endpoint configured in Starling dashboard
• N8N webhook workflow active Steps:

1. Configure test webhook
2. Make test transaction with Starling card
3. Record webhook receipt time vs. transaction time Expected Results:

• Webhook received within 10 seconds
• Transaction data complete Pass Criteria: Latency <10 seconds

​

TC-001.4: Pagination Support

• Historical transactions >100 records available Steps:

1. Request first page of transactions
2. Iterate through all pages using pagination tokens
3. Verify total count Expected Results:

• All transactions retrieved
• No duplicates
• Correct total count Pass Criteria: Complete transaction set retrieved

​

TC-001.7: Historical Import

• At least 6 months of transaction history
• WF-008 configured Steps:

1. Trigger historical import workflow
2. Specify date range: 6 months ago to today
3. Monitor import progress
4. Verify transaction count Expected Results:

• All historical transactions imported
• No errors or duplicates Pass Criteria: Complete import with 0 errors

​

9.2 Test Suite TS-002: Data Storage Tests

​

TC-002.1: Transaction Deduplication

• Test transaction in staging Steps:

1. Import transaction via API (first time)
2. Import same transaction again
3. Check Airtable record count Expected Results:

• Only one record exists
• Second import logged as duplicate Pass Criteria: Single record, no duplicates

​

TC-002.2: Record Creation with All Fields

• Test transaction with all metadata Steps:

1. Create transaction record
2. Verify all fields populated
3. Check data types Expected Results:

• All fields contain correct data
• Data types match schema Pass Criteria: All fields correctly populated

​

9.3 Test Suite TS-003: Categorization Tests

​

TC-003.7: Merchant Name Matching

• Categorization rules defined for known merchants Steps:

1. Create test transaction with merchant “Tesco”
2. Trigger WF-003
3. Verify category assignment Expected Results:

• Transaction categorized as “Groceries”
• Auto Categorized flag = true Pass Criteria: Correct category assigned

​

9.4 Test Suite TS-004: Budget Calculation Tests

​

TC-004.2: Calculate Total Spent

transactions = [
  { amount: -50.00, category: "Groceries" },
  { amount: -30.00, category: "Groceries" },
  { amount: -25.50, category: "Groceries" }
];

​

TC-004.6: Project End-of-Period Spend

periodStart = "2026-01-01";
periodEnd = "2026-01-31";
today = "2026-01-15";
spent = 300.00;
limit = 500.00;

• Days elapsed: 15
• Days remaining: 16
• Daily burn rate: £20
• Projected spend: £300 + (£20 * 16) = £620 Pass Criteria: Projection within ±5% of calculation

​

9.5 Test Suite TS-005: Alert Logic Tests

​

TC-005.1: 80% Warning Alert

• Category limit = £500
• No alerts in last 24h Steps:

1. Create transactions totaling £400
2. Wait for WF-004 calculation
3. Verify WF-005 triggers
4. Check alert record created Expected Results:

• Alert record with type=“warning”
• Notification sent Pass Criteria: Alert triggered at 80%

​

9.6 Test Suite TS-006: Notification Tests

​

TC-006.2: Email Notification

• SMTP configured
• Test email address Steps:

1. Trigger alert
2. Check email inbox
3. Verify email content Expected Results:

• Email received within 2 minutes
• Content includes all required information Pass Criteria: Email received with correct content

​

9.7 Test Suite TS-007: Enforcement Tests

​

TC-007.2: Manual Card Freeze

• Starling test account with active card Steps:

1. Trigger manual freeze via dashboard
2. Verify WF-007 executes
3. Check card status via API
4. Attempt test transaction Expected Results:

• Card status = frozen
• Transaction declined
• Enforcement log created Pass Criteria: Card successfully frozen

​

9.8 Test Suite TS-008: Dashboard UI Tests

​

TC-008.1: Display Budget Status

• Test data in Airtable
• Dashboard published Steps:

1. Open dashboard URL
2. Verify all sections load
3. Check data accuracy Expected Results:

• All sections visible
• Data matches Airtable records
• Visual indicators correct Pass Criteria: Dashboard fully functional

​

9.9 Test Suite TS-009: Performance Tests

​

TC-009.1: Budget Update Latency

• Create new transaction
• Measure time until dashboard updates Expected Result: <60 seconds
  Pass Criteria: 95th percentile <60s

​

TC-009.4: Dashboard Load Time

• Load dashboard with 12 months data
• Measure time to interactive Expected Result: <3 seconds
  Pass Criteria: Average <3s over 10 runs

​

9.10 Test Suite TS-010: Security Tests

​

TC-010.1: Credential Encryption

1. Inspect N8N credential storage
2. Attempt to read raw values
3. Verify encryption algorithm Expected Results:

• Credentials encrypted at rest
• Strong encryption used (AES-256) Pass Criteria: No plaintext credentials found

​

9.11 Test Suite TS-011: Reliability Tests

​

TC-011.1: API Retry with Backoff

• Simulate Starling API timeout
• Monitor retry attempts Expected Results:
• 3 retry attempts
• Delays: 5s, 15s, 45s
• Error logged after final failure Pass Criteria: Retry logic executes correctly

​

9.12 Test Suite TS-012: End-to-End Tests

​

TC-012.1: Complete Transaction Flow

1. Make real transaction with test card
2. Verify webhook receipt
3. Confirm categorization
4. Check budget update
5. Verify dashboard reflects change
6. Confirm no alerts (if under threshold) Expected Results:

• Transaction appears in dashboard within 2 minutes
• Correctly categorized
• Budget updated accurately Pass Criteria: End-to-end flow completes successfully

​

10. DEPLOYMENT SPECIFICATIONS

​

10.1 Infrastructure Requirements

• Self-hosted: VPS with 2GB RAM, 2 CPU cores, 20GB storage
• OR N8N Cloud: Starter plan minimum
• Node.js 18+
• PostgreSQL 13+ (for N8N data)

• Pro plan minimum (for API access, 50K records)
• Workspace with appropriate permissions

• Personal or Business account
• Developer access enabled
• OAuth application registered

• Email: SMTP server or service (SendGrid, AWS SES)
• Slack: Workspace and app credentials
• SMS (optional): Twilio account

​

10.2 Environment Configuration

STARLING_CLIENT_ID=<client_id>
STARLING_CLIENT_SECRET=<client_secret>
STARLING_REDIRECT_URI=<redirect_uri>
STARLING_ACCESS_TOKEN=<access_token>
STARLING_ACCOUNT_UID=<account_uid>
STARLING_CATEGORY_UID=<category_uid>

AIRTABLE_API_KEY=<api_key>
AIRTABLE_BASE_ID=<base_id>

SMTP_HOST=<smtp_host>
SMTP_PORT=<smtp_port>
SMTP_USER=<username>
SMTP_PASSWORD=<password>

SLACK_WEBHOOK_URL=<webhook_url>
SLACK_TOKEN=<bot_token>

TIMEZONE=Europe/London

​

10.3 Deployment Checklist

• Set up N8N instance
• Configure Airtable base with all tables
• Register Starling OAuth application
• Configure SMTP for notifications

• Deploy WF-001 (polling)
• Deploy WF-002 (webhook)
• Deploy WF-003 (categorization)
• Test transaction ingestion
• Configure webhook in Starling dashboard

• Create budget categories in Airtable
• Deploy WF-004 (calculations)
• Deploy WF-005 (alerts)
• Create initial categorization rules
• Test budget calculations

• Deploy WF-006 (notifications)
• Configure Slack integration
• Test all notification channels
• Set up notification preferences

• Deploy WF-007 (enforcement)
• Deploy WF-008 (historical import)
• Run historical import for baseline
• Deploy WF-009 (period rollover)
• Test enforcement actions

• Create Airtable interfaces
• Build budget dashboard
• Create transaction management view
• Configure mobile access
• User acceptance testing

• Set up workflow monitoring
• Configure error alerting
• Create system health dashboard
• Document troubleshooting procedures

• Execute full test suite
• Fix identified issues
• Perform end-to-end testing
• Create backup procedures
• Go live

​

10.4 Rollback Plan

• Critical workflow failures (>10% error rate)
• Data integrity issues
• Security vulnerabilities discovered
• Starling API changes breaking integration

1. Pause all workflows
2. Backup current Airtable data
3. Revert N8N workflows to previous version
4. Restore backed-up Airtable structure
5. Verify basic functionality
6. Resume monitoring

​

10.5 Backup & Disaster Recovery

• N8N Workflows: Version control in Git (daily commits)
• Airtable Data: Automated daily CSV export via API
• Configuration: Document all environment variables
• Retention: 30 days rolling backup

• Workflow Failure: Restore from Git, redeploy
• Data Loss: Restore from daily backup, re-run historical import
• Complete Failure: Rebuild from documentation, restore data

​

11. MAINTENANCE & SUPPORT

​

11.1 Ongoing Maintenance Tasks

• Monitor workflow execution logs
• Check alert delivery success rate
• Review uncategorized transactions

• Review categorization rule effectiveness
• Check budget adherence trends
• Update categorization rules as needed

• Archive old transactions (>24 months)
• Review and adjust budget limits
• Analyze spending patterns
• Update documentation

• Performance optimization review
• Security audit
• Backup restoration test
• User satisfaction review

​

11.2 Monitoring & Alerting

• Workflow execution success rate (target: >99%)
• API call success rate (target: >99.5%)
• Alert delivery success rate (target: >99%)
• Dashboard load time (target: <3s)

• 3 consecutive workflow failures
• API rate limit approaching
• Airtable record limit approaching (>45K)
• Security anomalies detected

​

11.3 Common Issues & Troubleshooting

​

11.4 Future Enhancements

• Machine learning for categorization
• Predictive budget recommendations
• Multi-currency support
• Family budget sharing
• Mobile native app
• Integration with other banks
• Voice assistant integration

​

12. ACCEPTANCE CRITERIA

​

12.1 System Acceptance

1. All Critical (P0) Requirements Met:
   • All FR requirements with Priority=Critical pass testing
   • All NFR requirements with Priority=Critical pass testing
2. Core Workflows Operational:
   • Transaction ingestion (polling + webhook) functional
   • Budget calculations accurate
   • Alerts triggered correctly
   • Notifications delivered successfully
3. Dashboard Functional:
   • Main budget dashboard loads and displays data
   • Transaction list accessible and filterable
   • All visualizations render correctly
4. Performance Targets Met:
   • Dashboard loads in <3 seconds
   • Budget updates within 60 seconds
   • 99.5% system uptime achieved
5. Security Requirements Met:
   • OAuth authentication working
   • Credentials encrypted
   • Audit logging in place
6. Documentation Complete:
   • User guide created
   • Technical documentation complete
   • Troubleshooting procedures documented

​

12.2 User Acceptance Testing (UAT)

1. Daily Use:
   • User makes transaction
   • Checks dashboard
   • Verifies categorization
   • Reviews budget status
2. Budget Management:
   • User adjusts budget limits
   • Creates new category
   • Updates categorization rules
3. Alert Handling:
   • User receives warning alert
   • Reviews spending
   • Takes corrective action
4. Monthly Rollover:
   • User reviews month-end report
   • Adjusts budgets for next period
   • Exports spending summary

• All scenarios complete without errors
• User can perform tasks without assistance
• System behavior matches user expectations
• No critical bugs identified

​

13. GLOSSARY

​

14. REFERENCES

​

14.1 External Documentation

• Starling Bank API Documentation: https://developer.starlingbank.com/docs
• N8N Documentation: https://docs.n8n.io
• Airtable API Documentation: https://airtable.com/developers/web/api
• OAuth 2.0 Specification: https://oauth.net/2/

​

14.2 Standards & Compliance

• PSD2 (Payment Services Directive 2)
• GDPR (General Data Protection Regulation)
• ISO/IEC 27001 (Information Security)

​

DOCUMENT CONTROL

• Technical Lead: _________________ Date: _______
• Product Owner: _________________ Date: _______
• QA Lead: _________________ Date: _______