Zaptra One

A studio like Zaptra runs dozens of relationships at once. Each one is a website build, a domain, hosting, a few invoices, maybe an instalment plan, and a steady stream of “small changes”. Before Zaptra One, all of that lived in different places: WhatsApp threads, email chains, bank-transfer slips, spreadsheets and people’s memory.

The result was predictable. Clients chased for updates. Designs were approved in a chat message that nobody could find a month later. Payments arrived by bank transfer with no reference. Domains and SSL certificates came close to expiring because the date lived in someone’s head.

There was a business problem underneath the operational one: Zaptra sold one-off projects. Once a site launched, the relationship went quiet until something broke. The studio needed a reason to stay connected — something that made everything it does for a client visible and renewable.

We started with a written blueprint of fifty numbered features (§01–§50) covering the full relationship: discover → quote → build → launch → monitor → grow → renew. Every feature has a status in a living handoff document, and every non-obvious choice is a numbered entry in a decisions log — more than 180 of them so far. That paperwork is what lets one small team, and AI coding agents, move fast without losing the thread.

The architecture follows from one idea: the organisation is the root of everything. Projects, invoices, websites, domains, requests, approvals, documents and notifications all hang off it. Two apps sit on one API — the portal the client sees and the admin Zaptra uses — so there is exactly one source of truth.

The second phase, codenamed IGNITE, moved the product from “show clients what we did” to “take a new customer from I need a website to a live site, domain and business email.” Its rule: one pipeline, two drivers. A capable client drives it themselves; a client who doesn’t use computers gets the same pipeline driven by Zaptra staff on their behalf. Same data, same automation, same billing — only who clicks changes.

Billing is the part of a client relationship where mistakes cost trust, so it got the strictest rules. Balances are never stored — they are derived from the payment ledger every time. Invoice status (draft, scheduled, partially paid, paid, overdue) is computed from dates and verified payments, not set by hand.

The core supports full payment, pay-as-you-progress, recurring subscriptions and LaunchPay™, Zaptra’s instalment programme: 30% upfront and the rest in equal monthly instalments over three or six months. A plan is a schedule of dated instalments with overdue tracking that completes itself when the last one is paid.

Because most Sri Lankan clients pay by bank transfer, the portal shows the bank details and the invoice number to use as a reference, then takes a photo, screenshot or PDF of the slip. Early in the second phase we found that an unverified payment could already count towards “paid”. That was harmless while only staff recorded payments, but not once clients could upload their own slips — so we fixed it before turning that feature on. Fulfilment is triggered only by verified money, never by invoice status. Anything that moves money takes an Idempotency-Key, so a retry can never charge twice.

The whole point of Zaptra One is that clients no longer have to ask. So every meaningful event raises a notification: it appears in the portal’s bell, and — unless a dedicated email already covers it — it is emailed from a verified Zaptra address.

Emails share one branded template shell, which also carries a banner Zaptra can change from the admin, so every transactional email doubles as a quiet marketing channel. Sending happens on a background executor, and notifying is deliberately best-effort: a failed email can never break the action that triggered it. Staff get their own alerts — a client replied, a slip was uploaded — in the team inbox.

Phone-number verification for self-serve sign-up goes out by SMS. Email and SMS both sit behind a provider interface: TechZap Infra can send them using the accounts it holds, and switching to a direct provider is a one-line configuration change kept as a rollback.

The backend’s integration tests boot the whole application against a real PostgreSQL in a throwaway container (Testcontainers), apply every migration, and exercise real HTTP requests. They cover authentication, tenancy isolation — another organisation’s data must be a 404 — and billing invariants. CI runs them on every push, and the deploy job will not ship if they fail.

New endpoints follow written API standards from day one: pagination on every list, filtering and sorting in the database against a whitelist, an index for every filtered column, no N+1 queries, validation at the edge, a consistent error shape, and an integration test covering the happy path, tenancy and validation.

Operations are documented as runbooks: deploying, migrating, rotating keys, restoring backups. The product’s own state — failed event deliveries, the fulfilment queue, AI spend — is visible to staff in the admin rather than buried in logs.

Two audiences, two kinds of documentation. For engineers: the blueprint (what the product is), the handoff (what is built and what is next), the vision and decisions log (why), runbooks, and API conventions. They are written so a new developer — or an AI agent — can pick up the work from one place.

For clients: a public help centre at help.zaptra.co, built with Astro Starlight and full-text search. Articles cover signing in, roles, following a project, approving work, asking for changes, sharing files, quotes, paying invoices, domains and business email — in English, Sinhala and Tamil.

The rule for every article: only describe what the portal actually does, checked against the screen or the code. Screenshots come from a local copy of Zaptra One seeded with a fictional client, “Sunrise Bakery” — the capture script refuses to run against anything but localhost, so no real client data can end up in public docs. When the portal changes, the screenshots are re-captured by script.