Architecture Overview

🔧 Technical Reference 12 min read Updated June 2026

Gridlock is a Node.js monolith with a pure HTML/CSS/JS frontend, six AI agent services, a Better-SQLite3 database, and a Cloudflare tunnel handling all public traffic. This document describes how every layer fits together — useful for contributors, integration partners, and MSP technical staff who want to understand what is running inside the shield.

System Architecture

All inbound requests flow through Cloudflare's edge, through the tunnel, into the Express HTTP server running on the homeserver, where they are routed to either static file serving (the frontend) or the API layer (agents, auth, dashboard, compliance). The AI agents call out to the Z.AI provider abstraction layer, which selects the appropriate upstream model and returns structured JSON. Results are persisted to SQLite and sent back to the browser.

Tech Stack

Every component in the stack was chosen for operational simplicity, not fashion. The constraint "never change the tech stack" exists precisely because this combination works reliably in production.

The Six AI Agents

Each agent is a service module in src/agents/ or src/services/. Agents share no direct memory — they communicate through the database and through the dashboard UI that orchestrates execution. An agent run is triggered by a user action or a scheduled job, constructs a prompt with the relevant context, calls the AI provider, parses the response, and writes the result to the appropriate database table.

Agent	Source File	Trigger	Primary Output
MSP Hunter	src/agents/msp-hunter.js	Manual execution or campaign schedule	Scored lead records written to leads table with contact data and email variants
Threat Researcher	src/services/threat-researcher.js	Manual prompt or CVE watchlist trigger	Threat brief with CVSS score, MITRE mapping, and remediation steps written to security_events
Tech Support	src/services/tech-support.js	Ticket submission via dashboard or API	Resolution steps appended to the ticket record; escalation flag set when confidence is low
Compliance Engine	src/services/compliance-engine.js	Manual audit trigger or scheduled weekly run	Compliance report with gap analysis written to compliance_reports
Account Manager	src/services/account-manager.js	Nightly scheduled job	Health score, churn risk flag, and expansion signals written to the organization record
Onboarding Agent	src/routes/onboarding.js	New account creation; re-triggered on each wizard step	Step completion events, initial security score seed, and guided tour state stored per user

AI Provider Abstraction Layer

All agent calls go through a thin abstraction layer rather than calling the AI provider SDK directly. This layer handles:

• Provider selection — Defaults to Z.AI GLM-5. A config flag enables fallback to an alternate provider (e.g., OpenAI-compatible endpoints) when GLM-5 is unavailable.
• Prompt construction — Each agent builds a structured system + user prompt. The abstraction layer injects organization context (industry, team size, compliance frameworks in use) into the system prompt automatically.
• Response parsing — The layer validates that the response matches the expected schema for each agent type. Malformed responses trigger a retry (up to 2 times) before surfacing an error to the user.
• Cost tracking — Token usage is logged per execution in the agent_executions table for plan-level throttling.

Database Schema

Gridlock uses a single Better-SQLite3 database file. All queries use parameterized statements — there is no string concatenation in SQL calls anywhere in the codebase. The key tables are described below.

users

Column	Type	Description
id	INTEGER PK	Auto-increment primary key
email	TEXT UNIQUE	User email address (login identifier)
password_hash	TEXT	bcrypt hash — plain text is never stored
name	TEXT	Display name
role	TEXT	admin or member
org_id	INTEGER FK	Foreign key to organizations
email_verified	INTEGER	0 or 1 boolean
created_at	TEXT	ISO 8601 timestamp

organizations

Column	Type	Description
id	INTEGER PK	Auto-increment primary key
name	TEXT	Organization display name
industry	TEXT	Industry vertical slug
team_size	INTEGER	Approximate headcount
plan	TEXT	starter, pro, or ultimate
security_score	INTEGER	Latest composite security score (0–100)
ls_customer_id	TEXT	LemonSqueezy customer identifier
created_at	TEXT	ISO 8601 timestamp

security_events

Column	Type	Description
id	INTEGER PK	Auto-increment primary key
org_id	INTEGER FK	Owning organization
type	TEXT	Event category (e.g. threat, dns_anomaly, compliance_gap)
severity	TEXT	critical, high, medium, or low
title	TEXT	Short human-readable event title
description	TEXT	Full event detail and AI-generated context
resolved	INTEGER	0 or 1 boolean
created_at	TEXT	ISO 8601 timestamp

agent_executions

Column	Type	Description
id	INTEGER PK	Auto-increment primary key
org_id	INTEGER FK	Owning organization
agent_id	TEXT	Agent slug (e.g. threat-researcher)
status	TEXT	pending, running, completed, or failed
input_prompt	TEXT	User-supplied prompt text
output	TEXT	Structured JSON result from the agent
tokens_used	INTEGER	Total tokens consumed (prompt + completion)
duration_ms	INTEGER	Wall-clock time of the AI call in milliseconds
created_at	TEXT	ISO 8601 timestamp

Other Key Tables

• compliance_reports — Stores full audit results per framework per org, including gap items and remediation status.
• leads — MSP Hunter prospects with composite score, sub-scores, contact data, pipeline status, and generated email variants.
• tickets — Support tickets with AI triage output, status history, and escalation log.
• cve_watchlist — Per-org CVE subscriptions with CVSS data, MITRE mapping, and last intelligence update timestamp.
• audit_log — Immutable record of all sensitive actions: logins, password changes, agent executions, billing events, and member changes, each with user ID, IP, and timestamp.

Security Architecture

Gridlock is a security product — it must be hardened against the same threats it helps customers detect. The security model is defense in depth across five layers:

Audit Logging

Every sensitive action is written to the audit_log table synchronously before the response is returned: user registrations, logins and logouts, password changes, agent executions, compliance report generation, billing events, team member additions and removals, and API key operations. Each record includes the user ID, IP address, user agent, action type, and a JSON payload with the relevant context. The audit log is append-only — no delete routes exist for it.

Billing Integration

Gridlock uses LemonSqueezy for subscription management. The billing flow works as follows:

1. When a user upgrades, the frontend redirects them to a LemonSqueezy-hosted checkout page with the organization's customer ID pre-filled.
2. On successful payment, LemonSqueezy fires a webhook to POST /api/billing/webhook.
3. The webhook handler verifies the request signature using the shared secret, then updates the organization's plan field in the database.
4. Subscription changes (upgrades, downgrades, cancellations) and payment failures all arrive via the same webhook endpoint and are handled by event type.
5. All billing webhook events are written to the audit log regardless of outcome.

Deployment

Production runs on a homeserver at 100.70.240.55, accessible publicly via a Cloudflare tunnel. The full deployment path from browser to database looks like this:

NSSM Service

The Node.js process runs as a Windows service managed by NSSM (Non-Sucking Service Manager). NSSM handles:

• Auto-restart on crash — If the process exits for any reason, NSSM restarts it within 2 seconds. There is no manual intervention required for transient failures.
• Startup at boot — The service starts automatically when the homeserver powers on, even after an unplanned reboot.
• Log capture — stdout and stderr are captured to rotating log files at C:\builds\gridlock\logs\.

Cloudflare Tunnel

The tunnel runs as a separate cloudflared process that maintains an outbound connection to Cloudflare's edge. There are no inbound ports open on the homeserver's firewall — all traffic enters through the tunnel. This means:

• The origin IP address is never exposed publicly.
• No port forwarding or NAT rules are required on the home router.
• Cloudflare's WAF rules apply before any request reaches the Node.js process.
• TLS is terminated at the Cloudflare edge; the tunnel uses its own encryption between the edge and the origin.

Deploying an Update

1. Push to master on GitHub.
2. SSH or RDP into 100.70.240.55.
3. Navigate to C:\builds\gridlock and run git pull origin master.
4. Run npm install if package.json changed.
5. Restart the NSSM service: nssm restart gridlock.
6. Verify the health endpoint: curl https://lockthegrid.com/api/dashboard/health.

Related