Client Ledger Dashboard (Community Edition)
CASE STUDY

Client Ledger Dashboard (Community Edition)

GitHubVisit Site
React 19TypeScriptViteSupabasePostgreSQLTailwind CSS v4Radix UILucide ReactWouterTanStack QueryFramer MotionVercel

An open-source, self-hostable client management and financial ledger platform built for freelancers, software agencies, and micro-consultancies. Centralizes client billing, project deliverables, VPS server credentials, internal tools, and PDF invoicing into a unified dashboard.

📊Executive Overview & Purpose

Client Ledger Dashboard is an open-source, self-hostable client management and financial ledger platform engineered specifically for freelancers, boutique software agencies, and micro-consultancies.

💡 The Problem It Solves

Independent developers and small agencies often juggle multiple client accounts across fragmented tools: spreadsheets for client billing, password managers for server credentials, separate software for invoicing, and bookmark bars for internal tools.

🚀 The Unified Solution

Client Ledger unifies these workflows into a single high-performance dashboard. It provides a centralized hub to track client revenue, project progress, infrastructure & credentials, internal tools, and printable PDF invoices.

🛠️Complete Technology Stack

The system is built with a modern frontend architecture, resilient backend infrastructure, and type-safe data pipelines.

LayerTechnologyPurpose & Usage
Frontend FrameworkReact 19Core UI library utilizing modern functional components and hooks.
LanguageTypeScript 5.9Strict type safety for data models (Projects, Invoices, VPS, Profiles).
Bundler & Dev ServerVite 7Lightning-fast HMR development server and production bundler.
Backend & DatabaseSupabaseCloud PostgreSQL database, Supabase Auth, and RESTful API layer.
Database EnginePostgreSQL 15Relational database with custom SQL triggers and Row Level Security (RLS).
Styling & DesignTailwind CSS v4Modern utility-first CSS framework with curated dark-mode color system.
UI PrimitivesRadix UIAccessible, unstyled UI components (Dialogs, Tooltips, Selects, Accordions).
IconsLucide ReactClean, consistent SVG icon set for UI actions and navigation.
RoutingWouterLightweight (1.5kB) client-side router for tab navigation and auth redirects.
Data FetchingTanStack Query v5Caching, deduplication, and efficient asynchronous state handling.
AnimationsFramer MotionSubtle, high-performance UI micro-animations and route transitions.
DeploymentVercelEdge network hosting with automated continuous deployment from GitHub.

🚀Core Modules & Features

Client Ledger Dashboard consists of six primary modules tailored for client operations and financial clarity:

1. Authentication & Role-Based Access Control (RBAC)

Built on top of Supabase Auth supporting distinct Admin and Client roles.

Features a Client Approval System: New client signups automatically start in a pending state until an Admin explicitly approves their portal access, protecting sensitive financial metrics and server details.

2. Financial Overview Dashboard

High-level metric scorecards calculating business performance in real time:

  • Total Revenue: Aggregate total contract value across all projects.
  • Collected Revenue: Actual payments received to date.
  • Outstanding Balances: Remaining unpaid balances requiring collection.
  • Collection Rate %: Visual progress bar showing payment collection health.

Real-time project distribution and status summaries (In-Progress, Completed, Not Started).

3. Project Management Ledger

Comprehensive project tracking for client accounts, contract values, milestone deliverables, and payment status.

Automated Balance Calculations: Dynamic formula Balance = Total Value - Amount Paid. Supports multi-field filtering by client name, project status, or instant search terms.

4. VPS Server Infrastructure Catalog

Centralized database for hosting & server infrastructure. Track provider (Hetzner, DigitalOcean, AWS), server IP addresses, SSH usernames, credentials, and deployed microservices.

🔒 Restricted strictly to Admin users for maximum infrastructure security.

5. Internal Tools Directory

Shared bookmark directory for internal micro-apps, uptime status checkers, and client tools. Features fast launch buttons for immediate team access and workflow speed.

6. Invoicing Engine & Printable Statements

Create custom line-item invoices with auto-calculated subtotal, tax/discount adjustments, and total due.

Print / Export directly to clean PDF formatting (invoice-template.tsx). Features automatic duplicate detection and sequential invoice numbering (e.g. INV-001, INV-002).

🔐Database Architecture & Security

The relational database schema is defined in supabase/schema.sql and consists of 6 core relational tables:

┌──────────────────┐
│   auth.users     │ (Supabase Auth)
└────────┬─────────┘
         │ 1:1
 ┌───────▼──────────┐
 │ public.profiles  │ (id, email, role, status)
 └──────────────────┘
         
┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐
│ public.projects  │    │ public.vps_servers│   │   public.tools   │    │ public.invoices  │
└──────────────────┘    └──────────────────┘    └──────────────────┘    └──────────────────┘
  • Row Level Security (RLS): Granular security policies enforced directly at the PostgreSQL database layer to restrict client access to their own data only.
  • Automated User Triggers: PostgreSQL function handle_new_user() runs automatically on user signup to generate linked profile rows.
  • Environment Variable Isolation: Public keys (VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY) are exposed via Vite build envs, while sensitive database credentials remain isolated.

⚡How It Was Built (Engineering Workflow)

  • Architecture & Design System: Designed a responsive UI layout with custom CSS variables, dark mode support, and persistent sidebar navigation (app-shell.tsx).
  • Context-Driven State Management: Created decoupled React Context providers (projects-context.tsx, vps-context.tsx, invoices-context.tsx) to manage data synchronization with Supabase.
  • Optimistic Local Updates: Implemented instant local UI state updates before network round-trips to deliver a snappy, zero-latency user experience.
  • Production Open-Source Packaging: Sanitized production data, added idempotent SQL migrations (schema.sql, seed.sql), and configured Vercel SPA rewrite rules (vercel.json).

FROM CONCEPT TO CODE </>

LET'S TURN IDEAS INTO SOLUTIONS

I'm available for full-time roles & freelance projects.

I thrive on crafting dynamic web applications
and delivering seamless user experiences.