Skip to content

roadmap.md

Latest commit

 

History

History
66 lines (50 loc) · 4.47 KB

roadmap.md

File metadata and controls

66 lines (50 loc) · 4.47 KB
Raw

Architecture Roadmap & Retrospective

This document outlines the completed capabilities (V1) and provides an engineering roadmap for future enhancements (V2) based on post-delivery reviews.

1. V1 Architecture Accomplishments

The initial release (V1) successfully delivered a secure, low-overhead business management platform. Key highlights include:

1.1 Secure Network Partitioning & Split Deployment

  • Implemented a unified codebase that registers routes conditionally depending on APP_MODE (public vs. admin).
  • Removed admin login interfaces from the public DNS surface area entirely.
  • Enforced zero-trust network access to the administrative API and database using a private Tailscale VPN mesh.

1.2 On-Premise Database Migration Path

  • Designed and documented the process of running a local, on-premise PostgreSQL instance on a standard office Linux PC.
  • Resolved dynamic ISP IP changes by routing database traffic over Tailscale’s stable 100.64.x.x IP overlay network, eliminating the need for paid static IP broadband upgrades.
  • Established automated nightly database backups using pg_dump + rclone pushing compressed archives to a secure Google Drive workspace with a 30-day retention policy.

1.3 Asynchronous Integration Ledgers

  • Implemented non-blocking background writes to Google Sheets using FastAPI BackgroundTasks.
  • Enforced a database-first model where PostgreSQL remains the single source of truth, and Google Sheets acts as a derived, write-only snapshot.
  • Structured all transaction synchronizations to be append-only to ensure reliability.

1.4 Resilient External API Integrations

  • Engineered a 30-day local PostgreSQL caching layer (gstin_cache) for the AppyFlow GSTIN verification API, reducing API usage costs by close to 100% for repeat buyers.
  • Enforced format validation (Layer 1 regex checks) at the server boundary to prevent invalid API lookups.
  • Implemented graceful UI/UX degradations, unlocking form fields for manual typing if the external API returns timeouts or quota exhaustion errors.

1.5 Strict Transactional Calculations

  • Configured PostgreSQL GENERATED ALWAYS stored columns to compute outstanding balances, preventing mathematical drift.
  • Enforced server-calculated status rules (PENDING, PARTIAL, PAID) while restricting manual overrides to CANCELLED actions.

2. V2 Architecture Roadmap

Following a production review, several areas have been identified for upgrade in the next iteration (V2).

gantt
    title V2 Engineering Roadmap
    dateFormat  YYYY-MM-DD
    section Identity & Access
    Cloudflare Access Integration    :active, cf1, 2026-06-01, 10d
    section Background Jobs
    Redis + Celery Message Queue    :cf2, after cf1, 14d
    section Sync Reliability
    Bi-directional Webhook Sync     :cf3, after cf2, 10d
Loading

2.1 Identity and Access: Transition to Cloudflare Zero Trust

  • Current Limitation: Enrolling client devices in Tailscale requires installing client applications, which introduces configuration friction for non-technical users.
  • V2 Solution: Deploy Cloudflare Access (Zero Trust) in front of the Vercel admin panel (admin.yourdomain.com).
  • Impact: Removes the client application requirement. Users authenticate against a Cloudflare identity wall (via email OTP or Google Workspace SSO) before the browser can retrieve or render the admin application bundle.

2.2 Background Jobs: Redis + Celery Message Queue

  • Current Limitation: FastAPI BackgroundTasks processes synchronization queues in-memory. If the server container restarts or crashes mid-sync, pending sync jobs are lost silently without execution.
  • V2 Solution: Integrate a Redis message broker with Celery workers.
  • Impact: Adds persistent message queues and automatic retry logic (with exponential backoff) for Google Sheets writes. If Google's API drops, jobs remain queued in Redis until recovery, preventing data loss.

2.3 Ledger Sync: Bi-directional Webhook Sync

  • Current Limitation: Google Sheets writes are append-only. If an administrator edits an existing sales entry in the database, the corresponding Google Sheets row is not updated.
  • V2 Solution: Store the Google Sheet row index (sheet_row_number) as a column inside the PostgreSQL tables during the initial insert sync.
  • Impact: Enables update triggers to locate the exact Google Sheet row index and execute targeted update requests, ensuring the accountant's spreadsheet remains in sync with the database even after edits.