# Scorpia CRM & Pipeline Desk

> **Status:** Previously live on production VPS (decommissioned 2026-08)  
> **Repository:** Private Internal Repository  
> **Tech Stack:** Next.js 16 (App Router), TypeScript, PostgreSQL, Prisma ORM, Better Auth, Tailwind CSS, Radix UI

---

## 1. Overview & Introduction
**Scorpia CRM** is a multi-tenant pipeline and client relationship desk engineered to manage candidate recruitment pipelines and freelance leads. Rather than treating leads as static database rows, Scorpia CRM treats each lead as an active contact card equipped with interaction histories, contextual notes, scheduled next steps, and credit-backed background actions.

## 2. The Operational Problem
While running talent acquisition pipelines at ZTE Corporation and freelance client projects, existing spreadsheet tools (Excel, Google Sheets) presented critical bottlenecks:
- Stale candidate notes and fragmented follow-ups across multiple team chats.
- No integrated ledger to account for the computational cost of background enrichment and data collection tasks.
- Inability to quickly pivot between recruitment stages (New → Contacted → Qualified → Proposal → Won).

## 3. System Architecture
```
[Client / Browser (Next.js 16)]
       │ (Better Auth Session Token)
       ▼
[Nginx Reverse Proxy (/services/crm)]
       │
[Next.js App Router & Server Actions]
       │
[Prisma ORM Client]
       ▼
[PostgreSQL Database (Multi-Tenant Workspaces, Leads, Credit Ledger)]
```

### Architectural Highlights
- **Multi-Tenant Workspace Provisioning:** Automatically initializes a scoped workspace upon user signup with isolated permissions and team member access.
- **Credit-Backed Ledger:** Background actions (such as automated enrichment, batch photo processing, and data ingestion) debit a unified workspace credit pool, preventing runaway external API bills.
- **Persistent Notes & Activity Feed:** Each contact record retains timestamped notes and status history to prevent context loss across team handoffs.

## 4. Key Features
- **Interactive Kanban Pipeline:** Drag-and-drop or status-click progression through 5 pipeline stages.
- **Quick-Log Notes & Contact Cards:** Fast inline editing for immediate note capture during candidate screening calls.
- **Credit Metering:** Direct balance tracking inside the workspace header.
- **Responsive Mobile & Desktop Shell:** Cohesive glassmorphism UI styled in graphite and Scorpia coral.

## 5. Security & Isolation
- Session management secured with HMAC cookie signatures.
- Better Auth configuration isolated to the `/services/crm` subpath to prevent cookie collision with other services.
- Data isolation enforced at the database query level via Prisma tenant IDs.
