# Architecture Patterns

**Domain:** Multi-tenant ISP Operations Management SaaS
**Project:** NetForge
**Researched:** 2026-03-04
**Confidence:** HIGH (established patterns, well-documented domain — verified against training knowledge through August 2025; external verification tools unavailable, document from domain expertise)

---

## Recommended Architecture

NetForge is best structured as a **modular monolith with tenant-scoped data isolation**, not microservices. For a small-to-medium SaaS targeting ISPs with under 500-5,000 subscribers per tenant, microservices add operational complexity that outweighs their benefits. A monolith with clear internal module boundaries allows rapid iteration, is easier to reason about, and can be extracted later if one module scales differently.

The core architectural principle: **every database query is scoped to a tenant_id**. This is enforced at the repository/data-access layer, not at the application layer. No business logic should ever bypass tenant scoping.

```
┌─────────────────────────────────────────────────────────────────┐
│                         Client Layer                            │
│   Admin Portal    Staff Portal    Collector App   Client Portal │
│   (web, full)     (web, full)     (web, mobile)   (web, limited)│
└──────────────────────────┬──────────────────────────────────────┘
                           │ HTTPS / REST or tRPC
┌──────────────────────────▼──────────────────────────────────────┐
│                      API Gateway / Auth Layer                   │
│   - JWT validation                                              │
│   - Tenant resolution (subdomain → tenant_id)                   │
│   - Role extraction                                             │
│   - Route-level permission guards                               │
└──────────────────────────┬──────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│                    Application Modules (Monolith)               │
│                                                                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │Subscriber│  │ Billing  │  │ Payment  │  │  Accounting   │  │
│  │  Mgmt   │  │  Engine  │  │ Tracker  │  │  (Ledger)     │  │
│  └──────────┘  └──────────┘  └──────────┘  └───────────────┘  │
│                                                                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ Ticketing│  │ Job Order│  │Technician│  │   Inventory   │  │
│  │ System   │→ │ Workflow │  │  Mgmt   │  │   (Assets)    │  │
│  └──────────┘  └──────────┘  └──────────┘  └───────────────┘  │
│                                                                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ Expense  │  │Dashboard │  │  Report  │  │ Notification  │  │
│  │ Tracking │  │& Metrics │  │ Engine   │  │  (Internal)   │  │
│  └──────────┘  └──────────┘  └──────────┘  └───────────────┘  │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                  Tenant Context Middleware               │  │
│  │     (all modules receive tenant_id from request ctx)    │  │
│  └──────────────────────────────────────────────────────────┘  │
└──────────────────────────┬──────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│                       Data Layer                                │
│   PostgreSQL (primary)      Redis (session/cache)               │
│   - tenant_id on all rows   - rate limiting                     │
│   - Row-Level Security      - background job queues             │
│   - Soft deletes            - temp calculations                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## Component Boundaries

### 1. Auth and Tenant Resolution

| Component | Responsibility | Communicates With |
|-----------|---------------|-------------------|
| Auth Module | JWT issuance, refresh, logout, session management | All modules (provides tenant_id + role to request context) |
| Tenant Resolver | Maps subdomain/slug to tenant_id, validates tenant exists and is active | Auth module, database |
| Permission Guard | Route-level RBAC enforcement based on role from JWT | All route handlers |

**Key rule:** The JWT payload carries `{ user_id, tenant_id, role }`. Every request arriving at the application layer already knows its tenant. No module may accept a request without tenant context.

**Role matrix summary:**

| Permission Area | Admin | Office Staff | Collector | Technician | Client |
|----------------|-------|-------------|-----------|------------|--------|
| Full system config | Yes | No | No | No | No |
| Billing & subscriber mgmt | Yes | Yes | No | No | No |
| Payment recording | Yes | Yes | Yes (own collections) | No | No |
| Ticket creation | Yes | Yes | No | No | Yes |
| Job order assignment | Yes | Yes | No | No | No |
| Job order completion | Yes | No | No | Yes (own) | No |
| Inventory adjustments | Yes | Yes | No | No | No |
| Accounting / journal entries | Yes | No | No | No | No |
| Own portal (view bills, pay) | No | No | No | No | Yes |

---

### 2. Subscriber Management

| Component | Responsibility | Communicates With |
|-----------|---------------|-------------------|
| Subscriber Module | Registration, plan assignment, status (active/suspended/disconnected), contact info | Billing engine (triggers first bill), Inventory (asset assignment), Auth (creates client portal account) |

**Data owned:** `subscribers`, `service_plans`, `subscriber_plan_history`

**Key boundary:** Subscriber management does not know about accounting. When a subscriber is activated, it emits an event (or calls a service interface) to the Billing engine. The Billing engine then creates the appropriate ledger entries via the Accounting module. Subscriber module never writes to the journal directly.

---

### 3. Billing Engine

This is the most complex module. It must handle prepaid and postpaid models with different logic.

| Component | Responsibility | Communicates With |
|-----------|---------------|-------------------|
| Billing Engine | Bill generation (scheduled + manual), billing cycle tracking, invoice creation, prepaid/postpaid logic, due date calculation, overdue detection | Subscriber module (read plan), Accounting module (write journal entries), Notification module (triggers bill-ready notices) |

**Prepaid logic:** Bill is generated before the service period begins. Subscriber must pay before activation or renewal. Overdue = service suspended.

**Postpaid logic:** Bill is generated at end of service period. Subscriber pays after consuming service. Overdue = follow-up by collector.

**Data owned:** `invoices`, `billing_cycles`, `billing_settings` (per tenant: cycle day, grace period, etc.)

**Key boundary:** The Billing engine does not record payments — that is the Payment Tracker's responsibility. An invoice has a status field (`unpaid`, `partial`, `paid`, `overdue`) that is updated by the Payment Tracker when a payment is recorded against it.

---

### 4. Payment Tracker

Tracks all money received. Collector-aware — the system must know which collector received which payment for reconciliation.

| Component | Responsibility | Communicates With |
|-----------|---------------|-------------------|
| Payment Tracker | Recording cash/online payments, linking payment to invoice, updating invoice status, collector balance tracking, reconciliation | Billing engine (read invoice, update status), Accounting module (write journal entry: cash received → accounts receivable cleared), Collector module (update collector running balance) |

**Data owned:** `payments`, `collector_remittances`, `payment_methods`

**Key design decision:** Payments are immutable once recorded. Corrections happen via reversal entries, not edits. This is essential for audit integrity and aligns with double-entry accounting principles.

**Collector flow:**
```
Collector records cash payment from subscriber
  → Payment created (linked to collector + invoice)
  → Invoice status updated (partially or fully paid)
  → Collector running balance increases (they are holding the cash)
  → When collector remits to office: remittance event created
  → Collector balance decreases, office cash account increases
  → Accounting module writes journal entries for both events
```

---

### 5. Accounting Module (Double-Entry Ledger)

The accounting module is a foundational module that every money-touching module writes to, but it does not initiate transactions itself.

| Component | Responsibility | Communicates With |
|-----------|---------------|-------------------|
| Chart of Accounts | Tenant-specific account structure (assets, liabilities, equity, income, expense) | All money modules (read accounts to post to) |
| Journal Entry Service | Creating balanced journal entries (debit = credit always), posting, voiding | Payment Tracker, Billing Engine, Expense Module, Inventory (asset capitalization) |
| Report Engine | Generating Trial Balance, Balance Sheet, Income Statement from journal entries | No writes — read-only from journal |

**Standard accounts (auto-provisioned per tenant at signup):**
```
Assets:
  - Cash (office)
  - Cash in Transit (collector-held)
  - Accounts Receivable (subscriber balances)
  - Inventory (network equipment)
  - Fixed Assets (deployed equipment)

Liabilities:
  - (minimal in v1 — can add later)

Equity:
  - Owner's Equity

Income:
  - Subscription Revenue

Expenses:
  - Technician Labor
  - Network Equipment (expense)
  - Operating Expenses
```

**Key rule:** Journal entries are never edited after posting. Corrections happen via reversing journal entries (a new entry that exactly offsets the original, then a correct entry). This is a non-negotiable accounting principle.

**Data owned:** `chart_of_accounts`, `journal_entries`, `journal_entry_lines`, `accounting_periods`

---

### 6. Ticketing and Job Order Workflow

These two are closely related but have distinct responsibilities.

| Component | Responsibility | Communicates With |
|-----------|---------------|-------------------|
| Ticket System | Receiving client issues (from client portal or staff manual entry), ticket lifecycle (open → assigned → resolved → closed), priority, category | Job Order module (a ticket can spawn one or more job orders), Subscriber module (read subscriber data), Notification module |
| Job Order Module | Technical work orders created from tickets, technician assignment, scheduling, completion recording, job type tracking | Ticket system (reads parent ticket), Technician module (assignment), Inventory module (parts used), Accounting module (record labor cost as journal entry) |

**Flow:**
```
Client submits ticket (portal) OR staff creates ticket (from call/text)
  → Ticket is open
  → Staff reviews → creates Job Order from ticket
  → Job Order assigned to technician
  → Technician completes job → marks completed (optionally with parts used)
  → If parts used → Inventory module decrements stock
  → Technician compensation calculated
  → Accounting: debit Labor Expense, credit Technician Payable
  → Ticket marked resolved
```

---

### 7. Technician Management

| Component | Responsibility | Communicates With |
|-----------|---------------|-------------------|
| Technician Module | Technician profiles, compensation model (per-job vs salary), job rate lookup by job type, compensation calculation, payroll summary | Job Order module (receives completion events), Accounting module (writes compensation journal entries) |

**Data owned:** `technicians`, `job_types`, `job_rates`, `technician_compensation_records`

**Two compensation models must coexist:**
- Per-job: each job order completion calculates `job_rate * completion` and credits technician payable
- Monthly salary: fixed monthly amount, booked at period end regardless of job count

---

### 8. Inventory Module

Manages two distinct concerns: stock on hand and deployed assets.

| Component | Responsibility | Communicates With |
|-----------|---------------|-------------------|
| Stock Management | Items in warehouse/storage, quantity tracking, purchase recording, low-stock alerts | Expense/Accounting module (purchase creates inventory asset entry), Job Order module (receives depletion events) |
| Asset Management | Equipment deployed to subscribers (router serial, ONU serial, location), asset lifecycle (deployed → returned → re-stocked or written off) | Subscriber module (asset linked to subscriber), Job Order module (technician records what was installed) |

**Data owned:** `inventory_items`, `inventory_categories`, `stock_transactions`, `deployed_assets`, `asset_assignments`

**Key distinction:**
- An item is "stock" until it is deployed to a subscriber address
- Once deployed, it becomes a "deployed asset" tracked per subscriber
- Return = asset moves back to stock (if functional) or written off (if damaged)

---

### 9. Expense Tracking

| Component | Responsibility | Communicates With |
|-----------|---------------|-------------------|
| Expense Module | Recording non-inventory operational expenses, category assignment, expense approval (optional), attachment of receipts | Accounting module (each expense creates a journal entry: debit Expense account, credit Cash or Payable) |

**Data owned:** `expenses`, `expense_categories`

---

### 10. Dashboard and Reporting

| Component | Responsibility | Communicates With |
|-----------|---------------|-------------------|
| Dashboard Service | Aggregating KPIs: total subscribers, active/suspended, monthly revenue, outstanding receivables, collector balances, open tickets, pending job orders | Read-only from all modules |
| Report Engine | Formal financial reports (Balance Sheet, Income Statement, Trial Balance), operational reports (collector reconciliation, technician productivity, inventory valuation) | Read-only from journal entries and operational tables |

**Key rule:** The Dashboard and Report Engine are read-only. They never write. All their data comes from the operational modules. Complex reports should be pre-computed on a schedule (via background jobs) rather than computed on-demand to avoid slow queries on large datasets.

---

### 11. Client Portal

| Component | Responsibility | Communicates With |
|-----------|---------------|-------------------|
| Client Portal | Subscriber-facing view: view current bill, payment history, submit support ticket, view service plan, view deployed equipment | Billing engine (read invoices), Payment Tracker (read payment history), Ticket system (create/read own tickets), Subscriber module (read own profile) |

**Key boundary:** The Client Portal is READ-HEAVY with one write action (submit ticket, initiate online payment). It is scoped strictly to the authenticated subscriber — a client JWT cannot access any other subscriber's data. This is enforced at both the permission guard layer AND the data access layer.

---

### 12. Notification Module (Internal)

| Component | Responsibility | Communicates With |
|-----------|---------------|-------------------|
| Notification Module | In-app notifications for staff (new ticket, job order assigned, overdue invoices), optionally email later | Receives events from Billing engine, Ticket system, Job Order module |

**Scope:** v1 should be in-app only (database-backed notifications, polled or WebSocket-pushed). Email/SMS integration is post-v1.

---

## Data Flow

### Money Flow (Complete Picture)

```
[Service Activation]
  Billing Engine generates Invoice
    → Invoice record created (status: unpaid)
    → Journal Entry: DR Accounts Receivable / CR Subscription Revenue

[Cash Payment via Collector]
  Collector records payment
    → Payment record created (linked to invoice + collector)
    → Invoice status updated (partial/paid)
    → Journal Entry: DR Cash in Transit (collector) / CR Accounts Receivable

[Collector Remits to Office]
  Remittance recorded
    → Journal Entry: DR Cash (office) / CR Cash in Transit (collector)
    → Collector balance zeroed

[Online Payment - future gateway]
  Payment gateway webhook → Payment Tracker
    → Same flow as cash minus collector step

[Expense Recorded]
  Expense Module creates expense
    → Journal Entry: DR Expense Account / CR Cash or Accounts Payable

[Inventory Purchase]
  Stock purchase recorded
    → Journal Entry: DR Inventory Asset / CR Cash or Accounts Payable

[Equipment Deployed (Capitalized)]
  Asset assigned to subscriber via Job Order
    → Journal Entry: DR Fixed Assets (deployed) / CR Inventory

[Technician Compensation (Per Job)]
  Job Order completed
    → Journal Entry: DR Labor Expense / CR Technician Payable

[Technician Paid]
  Payroll disbursement recorded
    → Journal Entry: DR Technician Payable / CR Cash
```

### Ticket-to-Resolution Flow

```
Client Portal or Staff Input
  → Ticket Created (open)
  → Staff Reviews
  → Job Order Created from Ticket
  → Technician Assigned (notification sent)
  → Technician Completes Work
    → Parts Used? → Inventory depleted
    → Job compensation calculated
  → Job Order Closed
  → Ticket Resolved
  → Client notified (in-app)
```

### Tenant Isolation Flow

```
Request arrives → DNS resolves subdomain (e.g., acme.netforge.app)
  → Tenant Resolver: subdomain → tenant_id (cached in Redis)
  → Auth validates JWT → extracts user_id, tenant_id, role
  → Request context carries { tenant_id, user_id, role }
  → Every repository method receives tenant_id as first parameter
  → All queries include WHERE tenant_id = ? as baseline
  → PostgreSQL Row Level Security as second defense layer
```

---

## Suggested Build Order (Phase Dependencies)

This ordering reflects hard dependencies — later components cannot function without earlier ones.

### Tier 1: Foundation (Must Build First)

These components have no dependencies on other domain modules.

1. **Tenant provisioning + Auth** — Without this, nothing is isolated or authenticated. All other modules receive tenant context from here.
2. **Chart of Accounts (Accounting Module — schema only)** — Every money event needs accounts to post to. Provision default accounts at tenant signup.
3. **Subscriber Management** — The core entity. Billing, inventory, and ticketing all reference subscribers.

### Tier 2: Core Operations (Depends on Tier 1)

4. **Billing Engine** — Depends on subscribers and service plans. Generates invoices.
5. **Payment Tracker** — Depends on invoices from Billing Engine. Records what comes in.
6. **Journal Entry Service** — Depends on Chart of Accounts. Now that billing and payments exist, we can post entries. Build this as a service that Billing and Payment Tracker call.

### Tier 3: Operational Modules (Depends on Tier 1 + 2)

7. **Inventory Module (Stock)** — Depends on Accounting (inventory purchases create journal entries).
8. **Expense Tracking** — Depends on Accounting (expense journal entries).
9. **Ticketing System** — Depends on Subscribers (tickets belong to subscribers).
10. **Job Order Module** — Depends on Tickets, Technician Module, Inventory (parts), Accounting (labor cost).
11. **Technician Management** — Can be built alongside Job Orders; they depend on each other.

### Tier 4: Visibility and Access (Depends on Tier 2 + 3)

12. **Dashboard and Metrics** — Depends on all operational modules being populated with data.
13. **Report Engine (Financial)** — Depends on Journal Entry Service having real data.
14. **Client Portal** — Depends on Billing Engine, Payment Tracker, Ticketing System.

### Tier 5: Enhancements

15. **Notification Module** — Can be added incrementally. Start with in-app, extend to email later.
16. **Asset Management** — Extends Inventory; tracks deployed equipment per subscriber.
17. **Collector Remittance Workflow** — Extends Payment Tracker.

---

## Architecture Decisions

### Decision 1: Shared Database with Row-Level Security

**What:** All tenants in one PostgreSQL database. Every table has `tenant_id`. PostgreSQL Row Level Security (RLS) policies enforce isolation at the database level as a backstop.

**Why:** Simpler to operate than per-tenant databases. Schema migrations run once. Connection pooling works. For SMB SaaS targeting small ISPs (not enterprise), this is the standard and correct approach.

**Tradeoff:** A noisy tenant (one ISP with 10,000 subscribers generating lots of queries) can affect others. Mitigation: rate limiting at the API layer, background job queuing.

**Confidence:** HIGH — this is the established pattern for SMB SaaS (used by Shopify, Linear, many others at this scale tier).

### Decision 2: Event-Driven Internally, Not a Message Bus

**What:** Modules communicate through in-process function/service calls, not a message queue. When the Billing Engine generates an invoice, it calls `AccountingService.postEntry(...)` directly. No Kafka, no RabbitMQ.

**Why:** A message bus is justified when modules are deployed separately (microservices) or when processing is async by requirement. For a monolith targeting sub-second response times on a small-medium dataset, synchronous in-process calls are simpler and correct. Async background jobs (via a job queue like BullMQ or pg-based queue) handle scheduled billing runs and report generation.

**Tradeoff:** If one module's accounting write fails, the whole transaction fails. This is actually correct behavior for financial data — you don't want a payment recorded without its journal entry.

**Confidence:** HIGH — this is the correct tradeoff for this scale.

### Decision 3: Double-Entry Enforced at Service Layer

**What:** The `JournalEntryService` is the only way to write to `journal_entry_lines`. It validates that debits = credits before persisting. No module writes directly to accounting tables.

**Why:** Prevents imbalanced books. A bug in the Payment Tracker cannot create an unbalanced journal entry if all writes go through a single service that enforces balance.

**Confidence:** HIGH — standard accounting software pattern.

### Decision 4: Immutable Financial Records

**What:** Payments and journal entries cannot be edited after creation. Corrections use reversal entries.

**Why:** Audit trail integrity. Tax compliance. Debugging is possible. Financial regulators (even informal ones like business owners doing year-end) need to see the full history of what happened, not what it looks like after edits.

**Confidence:** HIGH — non-negotiable for any accounting system.

### Decision 5: Collector Balance as Derived State

**What:** A collector's current cash balance is not stored as a single field. It is computed from: `SUM(payments.amount WHERE collector_id = X AND NOT remitted) - SUM(remittances.amount WHERE collector_id = X)`. This can be cached in Redis for performance.

**Why:** A stored balance field is prone to drift (bugs, race conditions). The authoritative answer always comes from the transaction log.

**Tradeoff:** Slightly more expensive to compute. Cache with a short TTL (or invalidate on new payment/remittance) to handle at scale.

**Confidence:** HIGH — event sourcing / derived state principle.

---

## Anti-Patterns to Avoid

### Anti-Pattern 1: Application-Layer-Only Tenant Isolation

**What:** Relying solely on `WHERE tenant_id = ?` in application code, without any database-level backstop.

**Why bad:** A single bug (missing WHERE clause) leaks data across tenants. This is a catastrophic security failure for a SaaS product.

**Instead:** Add PostgreSQL Row Level Security as a second layer. Even if the application omits the tenant filter, RLS prevents the query from returning another tenant's rows. Set RLS on every table that contains tenant data.

### Anti-Pattern 2: Billing Engine Writing Directly to Cash Tables

**What:** The Billing Engine or Payment Tracker directly incrementing/decrementing account balances in a "balances" table.

**Why bad:** Balance tables drift. Concurrent updates cause race conditions. You lose the transaction history needed for reconciliation.

**Instead:** No balance table exists. Balances are always derived from journal entry lines. `SUM(amount WHERE account_id = X AND type = 'debit') - SUM(amount WHERE account_id = X AND type = 'credit')` IS the balance. Cache for performance, but the source of truth is the ledger.

### Anti-Pattern 3: Merging Ticket and Job Order into One Entity

**What:** Treating "ticket" and "job order" as the same record.

**Why bad:** A single client issue might spawn multiple job orders (initial visit + follow-up). A job order might exist without a client ticket (proactive maintenance). They have different lifecycles, different owners (client-facing vs technician-facing), and different data shapes.

**Instead:** Keep them separate. Tickets have a `has_many :job_orders` relationship. Job orders have `belongs_to :ticket` (nullable for non-ticket-originating work).

### Anti-Pattern 4: Storing Computed Financial State

**What:** Storing "total revenue this month" or "outstanding balance per subscriber" as columns that get updated on every transaction.

**Why bad:** Race conditions. Bugs cause silent drift. Hard to audit. Hard to debug when numbers don't match.

**Instead:** Compute on demand from the ledger. Cache aggressively in Redis with appropriate invalidation. For reports, use materialized views or pre-computed report snapshots run on a schedule.

### Anti-Pattern 5: Granting Client Role DB-Level SELECT on All Tables

**What:** Building RBAC only at the API route level, without data-access-layer scoping for the client role.

**Why bad:** A client who discovers an API endpoint (through network inspection) can potentially access other subscribers' invoices if the data layer doesn't enforce subscriber-scoping on top of tenant-scoping.

**Instead:** Client Portal requests are scoped at TWO levels: tenant_id (from JWT) AND subscriber_id (from JWT). The data access layer for all client-facing queries adds `AND subscriber_id = ?` in addition to `AND tenant_id = ?`.

### Anti-Pattern 6: Soft Deletes Without Accounting for Them

**What:** Adding `deleted_at` soft deletes everywhere without ensuring all queries include `WHERE deleted_at IS NULL`.

**Why bad:** Deleted records silently appear in reports, counts, and joins if any query forgets the filter.

**Instead:** Use a database view or ORM default scope that filters deleted records. Alternatively, use PostgreSQL RLS to filter them. Never rely on developers remembering to add the filter manually.

---

## Scalability Considerations

| Concern | At 10 tenants (MVP) | At 100 tenants | At 1,000 tenants |
|---------|--------------------|-----------------|--------------------|
| Database size | Single PostgreSQL, no concerns | Same, add indexes | Consider read replicas for reports |
| Billing runs | Cron job, sequential per tenant | Background job queue with tenant workers | Distributed job queue (BullMQ), parallelized |
| Report generation | On-demand from ledger | Nightly pre-computed snapshots | Materialized views, async report jobs |
| Tenant isolation | RLS policies | Same | Same, plus connection pooling limits per tenant |
| API performance | No concerns | Cache hot reads in Redis | Horizontal API scaling, DB read replicas |
| Concurrent collectors | Not a concern | Optimistic locking on payment records | Same |

---

## Sources

All findings based on established SaaS architecture patterns, double-entry accounting principles, and multi-tenant database design patterns. External verification tools were unavailable during this research session.

**Confidence notes by section:**
- Multi-tenant shared DB with RLS: HIGH (industry standard, well-documented)
- Double-entry accounting patterns: HIGH (GAAP principles, stable for decades)
- Modular monolith over microservices for this scale: HIGH (well-established guidance from Martin Fowler, Sam Newman, others)
- Billing engine prepaid/postpaid model: HIGH (standard ISP billing concepts)
- Collector balance as derived state: HIGH (event sourcing principle)
- Specific framework/library choices: Deferred to STACK.md