Architecture
ClientFlo is built on a modern, modular stack. Each service has a clear responsibility and can be replaced or scaled independently. This section explains how the pieces fit together.
System Overview
ClientFlo follows a server-rendered frontend + backend-as-a-service pattern:
- Frontend: Next.js 16 with App Router, Server Components, and React 19. Deployed on Vercel or any Node.js server.
- Database: Firebase Firestore with real-time listeners. All data is stored in Firestore · no other database needed.
- Authentication: Firebase Auth handles sign-in, account management, and session tokens. The Admin SDK verifies tokens server-side.
- File Storage: Cloudinary for uploads and image optimization, with Firebase Storage as a fallback.
- Email: Resend (primary) or Brevo (fallback) for transactional emails.
- Calendar: Google Calendar API via OAuth 2.0 for calendar sync and Google Meet creation.
Module Architecture
Each workspace module (Leads, Projects, Invoices, Contracts, etc.) follows the same pattern:
| Layer | Technology | Responsibility |
|---|---|---|
| UI Components | React + shadcn/ui | Page layout, forms, tables, modals, drag-and-drop |
| Data Fetching | React hooks + TanStack Query | Firestore reads, caching, optimistic updates |
| State | Zustand | Workspace context, accent color, header state |
| Validation | Zod | Form validation, API input validation |
| API Routes | Next.js Route Handlers | Server-side operations (email, uploads, OAuth, meetings) |
| Database | Firestore | Real-time documents and collections per module |
Module Overviews
Presentation Layer
Next.js 16 + React 19 + Tailwind CSS 4
- Server-side rendering (SSR) and static generation (SSG) via Next.js App Router
- React 19 with Server Components for optimal performance
- Tailwind CSS 4 for utility-first responsive design
- shadcn/ui component library for a consistent design system
- Lucide icons for lightweight, tree-shakeable iconography
Authentication & Security
Firebase Authentication + Admin SDK
- Email/password authentication with Firebase Auth
- Google and GitHub OAuth sign-in options
- Role-based access control (Owner, Admin, Member, Viewer, Client)
- Module-level access controls per workspace role
- Firebase Admin SDK for server-side operations (API routes)
- Full audit trail logging for all workspace mutations
Data Layer
Firebase Firestore + Real-time Subscriptions
- Firestore for real-time data synchronization across clients
- Real-time listeners for instant UI updates on data changes
- Firebase Security Rules for row-level access control with workspace isolation
- Optimistic updates for responsive UI interactions
- Firebase Storage for document and file upload fallback
- Composite indexes for complex query patterns
Spreadsheet & Analytics
UniverJS + Custom Analytics Engine
- UniverJS powers the lead spreadsheet module with Excel-like functionality
- Custom analytics engine for project value, conversion rates, and cycle times
- Exportable reports for projects, invoices, and time tracking data
- KPI cards, time-series charts, pie/bar charts, and conversion funnels
- PDF export for reports and invoices
File Storage
Cloudinary (Primary) + Firebase Storage (Fallback)
- Cloudinary for document images, file uploads, and optimized delivery
- Automatic image optimization and responsive breakpoints
- Firebase Storage as a fallback storage provider
- 10 MB file size limit with drag-and-drop upload UI
Email & Notifications
Resend + Brevo Fallback
- Resend for transactional email delivery (3,000 free emails/month)
- Brevo as an alternative fallback provider (300 emails/day free)
- Open/click tracking via tracking pixel and link rewriting
- HTML email templates for invites, invoices, and notifications
- In-app notification bell with real-time unread counts
Calendar & Meetings
Google Calendar API + Google Meet
- Google Calendar OAuth integration for calendar sync
- Google Meet creation for video conferencing
- Public booking pages with timezone-aware slot selection
- Configurable meeting types with duration, buffer, and questions
- Conflict detection for meeting scheduling
Infrastructure & Deployment
Vercel + Node.js
- Vercel for instant deployment with automatic HTTPS and global CDN
- Node.js self-hosting option · run on any server
- Environment-based configuration for dev, staging, and production
- Stateless architecture · scale horizontally by adding instances
- Continuous deployment from GitHub · push to deploy
- Preview deployments for pull request testing
Data Flow
A typical data flow in ClientFlo works like this:
- Browser requesthits Vercel's edge network
- Next.js renders the page (SSR or SSG depending on the route)
- Client-side hydration activates React components
- Firestore listeners subscribe to real-time data for the active workspace
- User mutations (create, update, delete) go through:
- Firestore SDK for direct database operations (client-side writes)
- Next.js API Route for server-side operations (email, file upload, OAuth)
- Firestore security rules validate every read/write against workspace membership and role permissions
- Real-time updates propagate to all connected clients automatically
Security Architecture
ClientFlo uses defense-in-depth security across multiple layers:
| Layer | Protection |
|---|---|
| Edge | Cloudflare WAF (OWASP Core Ruleset, rate limiting, bot management, DDoS protection) |
| Application | Server Action re-authorization, Admin SDK confined to API routes, server-only guards, input validation with Zod |
| Database | Firestore security rules with role-based access, workspace isolation, owner-only operations |
| Authentication | Firebase Auth with optional MFA, custom password reset tokens (1hr expiry), rate-limited invite acceptance |
| Audit | Full audit trail (who, what, when) on all mutations |
Technology Stack
| Category | Technology |
|---|---|
| Framework | Next.js 16 (App Router) |
| Language | TypeScript 5.8 (strict mode) |
| UI | React 19, Tailwind CSS 4, shadcn/ui |
| State Management | Zustand 5, TanStack Query 5 |
| Database | Firestore (Firebase) with real-time listeners |
| Authentication | Firebase Auth + Firebase Admin SDK |
| File Storage | Cloudinary (primary), Firebase Storage (fallback) |
| Resend (primary), Brevo (optional fallback) | |
| Calendar | Google Calendar API / Google Meet |
| Spreadsheets | UniverJS |
| Charts | Recharts 2 |
| Forms | React Hook Form 7 + Zod 3 |
| Tables | TanStack Table 8 |
| Drag & Drop | @dnd-kit |
| CI/CD | GitHub Actions (lint, typecheck, build, Firestore deploy) |
| Hosting | Vercel (primary), any Node.js server (alternative) |
Free Tier Architecture
ClientFlo is designed to run entirely on free tiers. Here's how the services fit within their free limits:
| Service | Free Limit | Usage in ClientFlo |
|---|---|---|
| Firebase Spark | 50k reads/day, 20k writes/day | All database operations, authentication |
| Vercel Hobby | 100 GB bandwidth, 100k functions/month | Hosting, serverless functions, CDN |
| Cloudinary Free | 25 GB storage, 25 GB bandwidth | File and document uploads |
| Resend Free | 3,000 emails/month, 100/day | Transactional emails, invites, notifications |
| Google APIs | Free within quota | Calendar sync, Google Meet, OAuth |
A solo freelancer or small team will hit none of these limits in normal use. When you outgrow them, each service offers a cheap paid upgrade with no data migration needed.