System Architecture

Core Principles

• ✓ Ship working software to WeLink ASAP
• ✓ Keep current flat folder structure
• ✓ Add controllers/routes as needed
• ✓ Single Organization = WeLink
• ✓ Refactor when external customers demand it

Migration Triggers

Consider refactoring to modular structure when ANY of these occur:

Core Principles

• ✓ Group code by business domain (modules)
• ✓ Each module is self-contained
• ✓ Modules communicate through defined interfaces
• ✓ Multi-tenant from day one
• ✓ Any module can become a microservice later

Account & Access Models

How Modules Talk to Each Other

These are the gaps between the original Path B proposal and what MCP readiness requires. Each becomes a blueprint amendment plus an implementation task inside the phase it belongs to.

Files of Record

• ? Which module carves first in Phase 1 — Safety (well-bounded, drives Airtable sync) vs. Admin (smallest, lowest-risk practice migration)?
• ? MCP server hosting — same PM2 process as backend, or separate truxflow-mcp process?
• ? Rename Accounts (49-row expense-category table) to ExpenseCategory in a separate PR — kept distinct from TenantAccount to avoid naming collision.
• ? Airtable PAT rotation — deferred until later phases close; tracked in truxflow/secrets-rotation.md.

Dispatch Module — What Shipped (Apr 22, 2026)

Third module carved out the same day as Admin. Same discipline: literal code motion, (req, res) signatures preserved. Factoring (1026 LoC) assembled via cat+sed to guarantee a byte-identical body — only the import paths differ from the legacy controller.

Dispatch Module — Live Validation

Dead-code carry: legacy factoringController.js declared listCarrierFactoringAssignments but never wired a route for it. Preserved in the extracted service (Rule 4 — don't rewrite during extraction). Phase 2 cleanup can drop it.

Admin Module — What Shipped (Apr 22, 2026)

Second module carved out. Literal code motion — kept (req, res) signatures because Safety's (context, params) rewrite during extraction was the source of ~8 of the Apr 22 hotfix-sprint regressions. Phase 2 will do signature unification across Safety + Admin at once with Zod as the boundary.

Admin Module — Extraction Discipline Walk

Every regression the Safety extraction silently introduced (13 traced in the Apr 22 hotfix sprint) is represented in feedback/phase1-extraction-regressions.md. The Admin extraction was walked through the 9-item checklist for both services — 9/9 preserved.

Admin Module — Live Validation

User browser-walked the extracted surface on staging. Plus one end-to-end save on a real user (Moe Abraham) during testing.

Pre-existing Bug Surfaced During Testing

Not caused by the Admin extraction. In frontend/src/components/forms/UserForm.jsx, dirty-state detection misses several field changes — Save button stays disabled when the user edits firstName, toggles the Restricted/Unrestricted carrier radio, or removes a role chip. Typing digits into Phone does activate Save. Backend behavior is correct when Save eventually fires. Logged for follow-up; pre-dates the Admin extraction.

Guardrails Added

Four prevention measures to catch the kind of regressions that slipped through the initial Safety extraction (missing endpoints, shape mismatches, verb drift). All four run against modules/safety/* and are ready to apply to the next module extraction.

Parity Restorations (surfaced by the new tooling)

Frontend Regressions Fixed

File Layout Diff

Same HTTP surface, reorganized into the Path B modules/<name>/{service,transport-rest} layout. Old files remain in place during Phase 1 (still wired via server.js), but every Safety endpoint is now served by the new module.

Per-Endpoint Comparison

Generated via scripts/extract-routes.js. Empty diff = parity. ● same in both, ● new in modular, ● removed (none — all restored). Sub-router mounts expanded inline below each parent.

shared/ — Cross-Module Building Blocks

Zod 4.3.6 + Exemplar Schemas

One exemplar schema per module establishes the pattern. Full per-endpoint schemas grow inline with each module's Slice C/D/E migration — lazy expansion rather than big-bang schema write.

npm audit note: 35 pre-existing vulnerabilities (5 moderate, 29 high, 1 critical) surfaced during npm install zod. Unrelated to zod (4.3.6 is clean); project-wide dependency debt logged for a dedicated triage pass.

Slices C / D / E — Queued for Next Session

Browser-test checkpoint after each slice. Slice C can be narrowed to driver-only first if the full-Safety migration feels too broad at restart. See session-2026-04-22-phase2-prep.md for the restart pre-flight.

Phase 0 tenant scoping answers "which carriers does this tenant have?". It cannot answer "of those carriers, which has this specific user been allowed to see?". April 21 smoke test exposed the gap: revoking one carrier from a user still showed all carriers in the UI. The legacy User.carriers relation exists but is not read by any middleware.

Phase 1.5 collapses three pending concerns into one pass:

• Per-user carrier restriction (smoke-test gap)
• Department + action roles (Safety Officer, Accountant, Dispatcher, Admin, Super Admin)
• Tenant-type-aware defaults (Single-Carrier / Multi-Carrier / Service Provider)

{
  "sub": "user-abc",
  "tenantAccountId": "xyz",
  "tenantType": "SERVICE_PROVIDER",
  "isSuperAdmin": false,
  "isAdmin": false,
  "allowedCarrierIds": ["c1"],                        // one-carrier restriction
  "departmentsMap": {                                 // Phase 1.5 object
    "SAFETY": { "role": "Safety Officer", "actions": ["view","edit","delete"] },
    "TASKS":  { "role": "Safety Officer", "actions": ["view","edit","delete"] },
    "SETUP":  { "role": "Safety Officer", "actions": ["view","edit","delete"] }
  },
  "departments": ["SAFETY"],                          // legacy array (back-compat)
  "tokenVersion": 11
}

allowedCarrierIds is already the intersection of tenant.CarrierAccess.carrierIds ∩ user.carrierRestrictions.ids — computed at login, no request-time math. Frontend reads user.departmentsMap (preferred) or falls back to user.departments when it's the object shape (org-type sessions).

All non-admin presets include TASKS and SETUP so every role can see those universal tabs (per-department reflection of Tasks/Setup content handled in UI). DepartmentType enum: ACCOUNTING, DISPATCH, SAFETY, OPERATIONS, RECRUITING, TASKS, SETUP. Dispatcher's former OPERATIONS scope was dropped before Day 6 per tenant feedback.

verifyAccessToken        // decode + tokenVersion cache check
  ↓
restrictToTenantCarriers // JWT-read: req.carrierScope = allowedCarrierIds
  ↓
requireDepartment('SAFETY')   // NEW — department gate
  ↓
requireAction('edit')         // NEW — action gate
  ↓
handler

tokenVersion cache is in-memory Map with 60s TTL. Single PM2 process on staging makes Redis unnecessary. Cache interface abstracted so a Redis swap is later a one-file change.

Admin revokes carrier X from user U
  ↓
Transaction:
  - UPDATE user: tokenVersion += 1, carrierRestrictions disconnect X
  - Evict U from tokenVersion cache
  ↓
U's next request (old JWT)
  ↓
JWT tokenVersion (7) != DB tokenVersion (8) → 401
  ↓
Frontend: redirect to /login
  ↓
Re-login → new JWT without carrier X

Propagation: instant on cache eviction, max 60s via TTL expiry if eviction missed.

const { user } = useAuth();  // decoded JWT already in context

// No API calls below:
{user.departments.SAFETY && <SafetyNav />}
{user.departments.SAFETY?.actions.includes('edit') && <EditButton />}
<CarrierDropdown
  options={carriers.filter(c => user.allowedCarrierIds.includes(c.id))}
/>

Core Driver Information

TWIC & Company Information

Additional Driver Fields

Driver Documents (11 types)

Core Truck Information

Truck Status & Operations

Truck Documents (10 types)

Core Trailer Information

Trailer Status & Operations

Trailer Documents (6 types)

Postmark Integration

POST /api/webhooks/airtable/onboard

The shape of two humans on one VPS

Each human is a separate Linux user. Auto-memory, settings, and OAuth credentials are per-user by design — no shared MEMORY.md to corrupt. Global rules live in /opt/claude-shared/ and are read-only for both: when Moe edits a global rule, Shady's next session sees the update instantly.

Org → Workspaces → Members → Keys

Why /opt/claude-shared/ instead of /root/.claude/

/root/ is mode 700 — only root can read or traverse it. If shared rules stayed there, Shady couldn't follow a symlink into them. Moving them to /opt/claude-shared/ (mode 755, world-readable) lets both users symlink to the same source. One source of truth, two consumers.

What's shared vs per-user

The momentum question — answered

Per-user auto-memory does NOT mean Shady starts blind every session. The momentum on big projects lives in docs/SESSION-LOG.md, docs/decisions/, and docs/FIELD-REGISTRY.md — files that live inside the project's git repo, not in auto-memory. Both Claudes pull the same git, both load the same project docs at session start, both have full context.

Auto-memory is for per-human shorthand: "Moe prefers blunt pushback", "Moe is non-technical", "Moe's API key was rotated 2026-04-28". Shady's auto-memory holds his shorthand — and that's the whole point. Sharing it would actually be wrong.

Audit findings (2026-05-04) — what's actually wired up

Hybrid clone strategy for tomorrow

The default rule

• 📢 Announce before starting (Telegram/Slack/etc.) — "I'm on welink-ops for the next 2 hours"
• ⬇ Always git pull at session start
• ⬆ Always git push at session end — never commit and disappear
• ⚠ Shared files (prisma/schema.prisma, docs/03-DATA-MODEL.md, root config) — coordinate before touching mid-session

For TruxFlow specifically — concurrent module work

Both can work TruxFlow at the same time only if (a) different modules, and (b) docs are split per-module. Today the docs are still unified — that's a blocker we'll resolve in a follow-up session before any real concurrent work happens.

Different files = no merge conflicts. Each Claude session loads project-wide log + its module's log + its module's decisions.

For same-project, different-module concurrent work

Default: separate clones (per-user home). Same-project parallel work: add a worktree on a feature branch.

Worktree commands (for same-project parallel work)

Part A — Anthropic Console (✓ Complete 2026-05-04)

Part B — VPS Linux Setup (drafted; partial pre-stage done; execute 2026-05-05)

~5 of 9 phases pre-executed 2026-05-04 evening. Remaining (with Shady): ~10 min total — claude-mem plugin install + project clones + first-session test.

What we discovered while planning this

• 🔑 Two API keys live, both in same Anthropic account. WeLink-Sale-Bot is misnamed — it's actually Moe's general-purpose key. Momo1claude is the trading bot key, hardcoded in claude_bot.py + 6 backup copies.
• 💳 Claude Code uses subscription OAuth, not the API key. The ANTHROPIC_API_KEY in ~/.bashrc sits idle for Claude Code. Confirms zero double-billing.
• 🐙 3 GitHub remotes exist with deploy-key SSH aliases (TruxFlow backend, frontend, security-reports). 7 other projects have no GitHub remotes; welink-ops and 10-4Hire aren't even git repos.
• 🔒 API key plaintext leakage — same key appears in ~/.bashrc, PM2 dump, claude-mem logs, file-history snapshots, .bash_history. Rotation + scrub deferred to a future session.
• 📦 Claude Code and claude-mem are per-user installs. Shady will need both reinstalled in his account.
• 📊 Sales bot stopped logging April 7, trading bot zero usage in May. Either crashed or paused — diagnostic deferred.