ZippCRM Workflow Atlas

Platform Topology

How The Backend Team Uses ZippCRM

From the internal operations point of view, ZippCRM is the primary operating console. The backend team captures new business, converts leads, launches matters, routes work to teams, requests evidence, reviews uploads, approves effort, and publishes compliance updates.

Mission Control Control Desk Service Desk Ops Center

flowchart TD
    A["Internal user"] --> B["Mission Control"]
    B --> C["Control Desk"]
    C --> C1["Lead"]
    C1 --> C2["Client"]
    C2 --> C3["Project"]
    B --> D["Service Desk"]
    D --> D1["Assign to team"]
    D1 --> D2["Manager routes to consultant"]
    D2 --> D3["Consultant logs time"]
    D3 --> D4["Manager / reviewer approves"]
    B --> E["Regulatory Library"]
    E --> E1["Guidance"]
    E1 --> E2["Impact"]
    E2 --> E3["Workflow rule review / publish"]
    B --> F["Ops Center"]
    F --> F1["Email outbox"]
    F --> F2["Notifications"]
    F --> F3["Upload review"]
    B --> G["AI Copilot"]
    G --> G1["Chat"]
    G --> G2["Action drafts"]

What backend teams run here

Commercial intake and qualification.
Client and project setup with workflow and billing context.
Assignment routing, document requests, approvals, and audit logging.

What backend teams control

Who can move a matter ahead.
Which evidence is missing.
Which consultant and team own each work item.

Why this matters internally

Nothing depends on inbox memory alone.
Delivery and compliance stay in one system.
Customer communication, evidence, and audit history remain connected.

Commercial Lifecycle

How The Customer Experiences ZippCRM

From the customer point of view, ZippCRM is not an internal CRM. It is the portal where they receive credentials, understand what is pending, upload required files, and track work progress without repeatedly chasing the backend team.

Portal Login Status View Requests Uploads Effort Summary

1. Portal onboarding

Customer email is captured at lead or client stage.
ZippCRM creates a portal user for that customer.
Credentials are queued or sent from the system.

2. Matter visibility

Customer sees their projects and any standalone service items relevant to them.
Status, deadlines, and requested actions are visible in one place.
Approved effort summaries can be surfaced for transparency.

3. Document response

Backend team raises a document request from ZippCRM.
Customer receives the request and uploads the file through the portal.
The upload moves into the internal review queue.

4. Ongoing confidence

Customer does not have to ask what is pending.
Customer does not have to ask where to send files.
Customer sees a structured engagement instead of fragmented mail threads.

Business object	Key captured data	Why it matters
Portal credentials	Portal email, contact name, password setup	Brings the customer into the same operating system as the backend team
Status visibility	Projects, standalone service items, progress, deadlines	Reduces manual follow-up and confusion
Document response	Requests, uploads, review state	Moves evidence collection into a controlled loop
Effort visibility	Approved time and monthly statement export	Improves transparency around work done

Workflow Families

How Delivery Runs Between Backend And Customer

This is the shared operating model. Internally, the team works mainly through projects, with Service Desk reserved for non-project work. Externally, the customer sees status, requests, uploads, and approved effort. ZippCRM connects both sides without losing control.

Projects Assignments Teams Customers

flowchart TD
    A["Lead / Client"] --> B["Regulatory Project"]
    A --> C["Assignment"]
    B --> D["Onboarding -> Documentation -> Filing -> Liaison -> Issue"]
    D --> E["Checklist verification + document vault + billing milestones"]
    C --> F["Assigned to team"]
    F --> G["Team manager routes to consultant"]
    G --> H["Consultant logs time"]
    H --> I["Manager / reviewer approves effort"]
    I --> J["Client sees summary and statement"]

Regulated project path

Each workflow family uses the same stage-gate frame with different checklist content.
Mandatory evidence must be verified before stage progression.
Document requests, liaison logs, expiry alerts, and milestone billing live inside the project record.

Assignment path

Used for accounting, GST, legal, secretarial, advisory, banking, and ad hoc regulator-linked work.
The standalone service item is owned by a team first, then routed by the team manager to named consultants.
Multiple time entries, billable flags, and monthly statements are supported.

Customer collaboration path

Customer receives requests from ZippCRM instead of informal follow-up.
Customer uploads into the portal instead of replying with attachments everywhere.
Backend team reviews, accepts, and continues execution from the same system.

Portal, Governance, And AI

Shared Controls Between Backend And Customer

The backend team and the customer do not use the product in the same way, but they depend on the same control layer: permissions, document handling, notifications, audit history, and governed compliance updates.

RBAC Documents Notifications Audit

Control	Backend view	Customer view
RBAC	Internal roles govern write, review, billing, and user management.	Customer sees only their own records and upload actions.
Document vault	Backend team stores, reviews, and manages matter evidence.	Customer uploads directly into the right record.
Notifications	Ops center shows email, uploads, and internal events.	Customer gets a clearer request-and-response loop.
Audit + governance	Backend team gets operational accountability and regulated change control.	Customer benefits from a more reliable and traceable service process.

Client Portal

Customer collaboration surface

Customers log in, see status, respond to requests, and upload evidence without leaving the system.

Regulatory Library

Backend governance engine

Backend teams convert RBI, SEBI, and IRDAI guidance into reviewed workflow rule changes.

Ops Center

Operational follow-through

Emails, notifications, and upload review queues give the backend team a visible follow-up console.

AI Copilot

Internal acceleration

Admin-managed AI settings support chat and draft generation for backend teams without exposing admin tools to customers.

Current Build — Updated April 2026

Current Runtime Baseline

This is the practical technical baseline that supports both the backend team workflow and the customer portal experience. All systems are confirmed operational as of April 2026.

Enterprise Licensed PostgreSQL-backed Role-aware UI Portal-enabled AI-enabled Multi-deployment

System Health Snapshot

License

✓ ENTERPRISE — 500 seats

Valid until 31 Dec 2031

Auth

✓ JWT — email field login

Admin: admin@zippcrm.local

Scheduler

✓ Active — automation backfill done

Single-pod safe (SCHEDULER_ENABLED flag)

Storage

✓ Volume-persistent

S3-compatible optional override

AI Copilot

✓ Anthropic + OpenAI ready

Keys injected via .env

Comms

⚙ SMTP + WhatsApp optional

Configure in Admin → Settings

Frontend

Mission Control, Leads, Projects, Service Desk, Regulatory Library, Ops Center, AI Copilot, User Admin, and Workflow Atlas.
Readable control-desk forms with field guidance and inline validation states.
Role-aware views for internal teams and client users. Login field is email (not username).

Backend

Python API with workflows, leads, clients, projects, service items, timesheets, notifications, AI settings, and audit logging.
Billing engine: project-linked invoice lifecycle (draft → sent → overdue → paid), GST/TDS calculation, client-level ledger API, credit notes (CN-YYYY-NNNNNN), and daily overdue scheduler with email + in-app push alerts.
PostgreSQL 16 as the system of record for operational, security, and governance entities.
Persistent document file storage on a dedicated volume; optional S3/MinIO override via environment variables.

Operational engine

Workflow templates for RBI, SEBI, and IRDAI seeded at boot.
Assignment desk supports team-owned service work and consultant allocations.
Stage progression and effort approval both have controlled review paths.

Client and governance controls

Client portal users are created from contact email and can receive credentials from ZippCRM.
Regulatory library supports draft, review, approve, and publish flows for workflow changes.
AI Copilot uses shared provider settings and action drafts for operational acceleration.

Infrastructure

Deployment Options

ZippCRM can be deployed on Docker (recommended for getting started), Kubernetes (production scale), or directly on Linux or Windows servers (bare metal / VM).

🐳 Docker ☸️ Kubernetes 🐧 Linux 🪟 Windows

🐳 Docker (Recommended)

Three containers: postgres, backend, frontend. Starts with a single docker compose up -d.
All config lives in .env — this file takes precedence over docker-compose.yml defaults. Always update both when changing keys.
Ports: Frontend on 3002, Backend API on 8088, Postgres on 5436.
Upgrade: replace image, run docker compose up -d --build. Data volumes persist across rebuilds.

☸️ Kubernetes / Helm

Deploy backend as a Deployment with ≥2 replicas behind a ClusterIP Service. Use HorizontalPodAutoscaler (CPU 70%) for elastic scale.
All secrets injected via a Kubernetes Secret object — never bake credentials into the image.
Scheduler isolation: Set SCHEDULER_ENABLED=true on exactly one replica (dedicated single-replica Deployment). Running the scheduler on every pod causes duplicate job execution.
PostgreSQL should use an external managed service (AWS RDS, GCP CloudSQL) in production. Use an ExternalName Service or direct DATABASE_URL secret.
Use PersistentVolumeClaim with ReadWriteMany (NFS/EFS) for shared document storage across replicas, or switch to S3-compatible object storage via the S3_* env vars.
Ingress: configure TLS termination at the Ingress controller (nginx-ingress or AWS ALB). Set PORTAL_URL to your public HTTPS domain.

🐧 Bare Metal — Linux (Ubuntu 22.04)

Requirements: Python 3.12, PostgreSQL 16, Nginx, Certbot. Install via apt + deadsnakes PPA.
Run backend as a systemd service under a dedicated zippcrm system user. Set Restart=on-failure and RestartSec=5.
Nginx reverse-proxies localhost:8080 (backend) and serves the frontend/ static files. Enable TLS with certbot --nginx.
All environment variables set in the [Service] Environment= block of the systemd unit file, or via an EnvironmentFile= pointing to /etc/zippcrm/.env.
Database connection: DATABASE_URL=postgresql://zippcrm:zippcrm@localhost:5432/zippcrm.

🪟 Bare Metal — Windows Server

Requirements: Python 3.12 (winstore or python.org), PostgreSQL 16, Nginx for Windows. Easiest via Chocolatey: choco install postgresql16 python312 nginx.
Run backend as a Windows Service using NSSM (Non-Sucking Service Manager): nssm install ZippCRMBackend python app.py. Set startup directory, stdout/stderr log paths, and environment variables in the NSSM GUI.
Nginx serves static frontend files and reverse-proxies the API. Place config in C:\nginx\conf\zippcrm.conf.
For HTTPS on Windows use win-acme (Let's Encrypt ACME client for IIS/Nginx on Windows).
Service management: nssm start ZippCRMBackend / nssm stop ZippCRMBackend / nssm restart ZippCRMBackend.

Critical Environment Variables

DATABASE_URL
Full PostgreSQL connection string

ZIPPCRM_LICENSE_KEY
Enterprise key — must match in both .env and docker-compose.yml

PORTAL_URL
Public URL customers use to reach the portal (sets CORS + email links)

ANTHROPIC_API_KEY / OPENAI_API_KEY
AI Copilot providers (either or both)

SMTP_HOST / SMTP_USERNAME / SMTP_PASSWORD
Email notifications; can also be set post-boot in Admin → Settings

S3_ENDPOINT / S3_BUCKET / S3_ACCESS_KEY / S3_SECRET_KEY
Optional object storage override for documents (multi-pod / Kubernetes)

WHATSAPP_BSP_URL / WHATSAPP_TOKEN / WHATSAPP_NUMBER
WhatsApp BSP integration for client notifications

SCHEDULER_ENABLED
Set true on exactly one replica only (Kubernetes / multi-instance)

Revenue Operations — Updated April 2026

Billing, Invoicing & Credit Control

ZippCRM's billing engine sits directly inside the project and client record. Milestones generate invoices; invoices flow through draft → sent → paid (or overdue). Credit notes correct errors. The daily scheduler auto-marks overdue invoices and triggers email reminders without manual intervention.

GST Compliant TDS-aware Credit Notes Overdue Alerts Client Ledger

flowchart TD
    A["Client"] --> B["Project"]
    B --> C["Billing Milestone"]
    C --> D["Invoice (DRAFT)"]
    D --> E["Send to client → SENT"]
    E --> F{"Payment received?"}
    F -->|"Yes"| G["Mark PAID"]
    F -->|"No — due_date passed"| H["Scheduler: mark OVERDUE"]
    H --> I["Auto email reminder → client contact"]
    H --> J["In-app push → ops team"]
    G --> K["Close milestone"]
    D --> L["Error found?"]
    L -->|"Yes"| M["Issue Credit Note CN-YYYY-NNNNNN"]
    M --> N["Adjust client balance"]
    A --> O["GET /clients/cid/invoices — full ledger view"]
    O --> P["All invoices across all projects for this client"]

Invoice lifecycle

Invoices are created at the project billing milestone level. Each milestone holds amount, due date, and GST details.
Status flow: draft → sent → paid. Overdue is set automatically by the scheduler when due_date < today and status is still sent.
Manual PATCH to status paid also allowed for ops staff marking cash receipts.

GST & TDS rules

CGST + SGST (9% + 9%) for same-state transactions; IGST 18% for inter-state.
TDS is deducted before the net payable is shown on the invoice PDF.
GST number, client PAN, and billing address are captured at the client record and auto-filled on the invoice.

Overdue & reminder automation

Daily scheduler calls mark_overdue_invoices() — flips all sent invoices past due date to overdue.
Immediately followed by trigger_invoice_overdue_alerts() — sends a branded HTML email to the client contact and an in-app push to the ops team.
Controlled by the invoiceOverdueAlerts notification setting. Can be toggled in Admin → Notification Settings.

Credit notes

Issued against a specific invoice. Number format: CN-{YEAR}-{SEQ:06d} (e.g., CN-2026-000001).
Stored in credit_notes table (auto-created on first use — no migration needed).
Only staff roles can issue credit notes. creditAmount must be greater than zero.
Client sees the credit note linked to the relevant invoice in their portal.

API Surface — Billing Routes

Billing API Endpoints

All endpoints are authenticated via JWT. Client-scoped users only see their own invoices. Staff roles have full access including overdue listing and credit note issuance.

Method & Path	Who can call	Purpose
`GET /clients/{cid}/invoices`	Staff + scoped client user	Unified ledger — all invoices across all projects for this client
`GET /projects/{pid}/invoices`	Staff + scoped client user	Invoice list for a single project
`POST /projects/{pid}/invoices`	Staff only	Create a new invoice (draft) linked to a billing milestone
`PATCH /invoices/{inv_id}`	Staff only	Update status (draft → sent → paid / overdue), due date, or amounts
`GET /invoices/overdue`	Staff only	All overdue invoices across all clients — ops dashboard feed
`GET /invoices/{inv_id}/credit-notes`	Staff + scoped client user	All credit notes linked to a specific invoice
`POST /invoices/{inv_id}/credit-note`	Staff only	Issue a credit note (requires reason + creditAmount > 0)

Data Objects

Billing Object Model

The billing layer sits on top of projects. A project has many milestones; each milestone can produce one invoice; each invoice can have multiple credit notes.

erDiagram
    CLIENT ||--o{ PROJECT : "has"
    PROJECT ||--o{ BILLING_MILESTONE : "has"
    BILLING_MILESTONE ||--o| INVOICE : "generates"
    INVOICE ||--o{ CREDIT_NOTE : "corrected by"
    INVOICE {
      int id
      string invoice_number
      string status
      date due_date
      decimal amount
      decimal gst_amount
      decimal tds_amount
      string gstin
    }
    CREDIT_NOTE {
      int id
      string credit_number
      int invoice_id
      string reason
      decimal credit_amount
      string status
    }

Invoice statuses

draft — Created, not yet sent to client
sent — Emailed or shared with client, awaiting payment
paid — Payment confirmed by ops team
overdue — Past due date, not paid (set by scheduler)

Notification triggers

invoice_created — ops team notified when a new invoice is raised
invoice_sent — client receives the invoice via email
invoice_overdue — daily scheduler triggers email + push (new)
credit_note_issued — client notified of credit adjustment