Client Delivery Without Owner Memory
The Situation
Client Management Portal is an internal operating system for small agencies and solo delivery teams that need one place to run intake, onboarding, project delivery, task requests, reports, documents, and follow-up.
Teams need it when the client relationship lives in five places: a sales inbox, an onboarding form, a project thread, an invoice tool, and the founder's memory. The risk is not only that someone misses a task. The bigger risk is that each tool tells a different story about the same client.
This build replaced spreadsheet tracking, copied onboarding docs, scattered client requests, and owner-memory status checks with a tenant-scoped portal and CLI. The codebase proves the shape: 5 client statuses, 6 project statuses, 3 auth modes, 25 route files, and operator surfaces for due work, stale work, SLA checks, handoff summaries, report drafts, capacity, asks, and reply drafts.
The Cost of Doing Nothing
The repo does not contain real payroll or contract values, so the money here is conservative operating math, not a revenue claim. If one operator spends 30 to 90 minutes per workday reconciling client state at €25 to €45 per hour, the coordination drag sits around €3,250 to €17,550 per year before churn, rework, or missed scope.
That number is only the visible cost. The hidden cost is worse: stale leads that need a 60-day cleanup job, support work that crosses an 80 percent capacity warning, bug reports that need to be classified as asks, and overdue reports or documents that surface in the operator digest. Without a single record, the team pays for every handoff twice: once when the work happens, and again when someone reconstructs what happened.
What I Built
I built one client-state core with separate entry points for each actor.
Clients use the portal to see updates, submit tasks, search their project history, and attach files. Operators use the CLI and admin API to create clients, move projects, record capacity, prepare report drafts, triage stale work, and generate handoff summaries. External systems push metrics, Docs sends document and invoice events, and Notification Hub handles outgoing client communication.
The hard part was not making another dashboard. The hard part was deciding which facts are safe for the client to see, which facts must stay internal, and which actions are allowed to trigger a notification. That boundary appears across projects, tasks, updates, comments, documents, invoices, capacity, report drafts, and milestone completion.
System Flow
Data Model
Architecture Layers
The Decision Log
| Decision | Alternative Rejected | Why |
|---|---|---|
| Keep client-visible and internal state in the same operating record | Separate tools for internal notes and client updates | Delivery work needs one source of truth, but visibility fields prevent internal notes from leaking into the portal. |
| Use Notification Hub as a soft dependency | Build email delivery into the portal | Client work should not stop because email delivery is down. The portal emits events, logs failures, and keeps the state change. |
| Make the CLI a primary operator surface | Wait for every admin screen before operating | The owner and VA can run client, project, queue, stale, due, handoff, and report commands from the terminal while the portal remains client-facing. |
| Use state transitions instead of freeform statuses | Let operators type any status | Client and project movement is limited to known paths, which makes handoff safer and keeps the portal from showing nonsense. |
| Add capacity budgets and report drafts as records | Treat scope and reporting as notes | Scope pressure and client reporting are business objects. They need approval state, visibility, and audit history. |
| Cache Docs and metrics data inside the portal | Pull every document or metric live on every view | The portal needs status and history even if another service is slow. External systems can push into a tenant-scoped cache. |
Ecosystem Integration
The portal owns client state, not every delivery mechanism around it. Client-facing events flow into the notification hub, which handles channel delivery outside this codebase. Document and invoice status comes from Klevar Docs, while attachments sit in Supabase Storage with portal metadata in Postgres. Both integrations are feature-flagged. The system runs standalone with no ecosystem dependencies.
Results
The result is an operating record rather than another client dashboard. Intake submissions can become clients. Projects carry 6 delivery states. Clients can submit requests with attachments. Operators can inspect due work, stale work, SLA risk, asks, report drafts, and handoffs from the CLI. The latest recorded regression gate reached 416 total tests, with 398 passing and 18 intentionally skipped, plus typecheck, backend build, CLI build, and bounded real-server E2E passing.
The first value shows up when a client asks for status and the answer no longer depends on the founder's memory. The second value shows up when a VA can run the same queue and handoff commands without guessing which updates are safe to expose. The current architecture fits an internal agency system. Past that, the next limit is not the data model. It is moving cron and high-volume writes out of the API process before the operator layer becomes a shared SaaS product.