NexCRM Documentation

NexCRM is a workspace-first CRM SaaS for sales and operations teams who need structured follow-up, pipeline visibility, and AI-assisted decision support — without enterprise bloat. Leads become follow-ups; follow-ups become revenue.

Primary users

Sales reps, sales managers, and ops coordinators in SMB teams (1–50 people).

Core value

Single workspace for leads, pipeline, contacts, tasks, and revenue workflows with optional AI assistance.

Deployment

Next.js frontend monorepo; Supabase for auth, data, and RLS; Gemini for AI generation.

Small and mid-size teams running revenue on spreadsheets, email threads, and ad-hoc notes. They lack a shared system of record for leads, deals, and follow-ups — especially when proposals, projects, and campaigns enter the picture.

• Leads and deals live in disconnected tools; pipeline truth is unclear.
• Follow-ups slip because tasks and calendar events are not tied to CRM records.
• Reps rewrite the same emails, summaries, and proposals from scratch.
• Managers cannot see workload, risk, or campaign performance in one place.
• Generic CRMs are either too heavy (Salesforce) or too shallow (spreadsheet + inbox).

Role

Individual contributor closing deals

Goals

Know what to do next, draft follow-ups fast, move deals through stages

Pain points

Context switching, manual note-taking, unclear priorities

JTBD

When a lead responds, I want the next action surfaced so I can reply within minutes, not hours.

Role

Leads a team of 3–15 reps

Goals

Pipeline visibility, campaign oversight, team performance

Pain points

Stale CRM data, no audit trail, fragmented reporting

JTBD

When reviewing the week, I want accurate pipeline and task completion so I can forecast and reassign work.

Role

Founder or ops lead who owns the workspace

Goals

Invite team, configure pipeline, control billing and integrations

JTBD

When onboarding a new hire, I want them in the workspace with the right role in under five minutes.

1. Capture a lead from inbound or outbound activity.
2. Qualify and convert to a contact linked to a company account.
3. Create a deal on the pipeline and move through configured stages.
4. Schedule follow-ups as tasks and calendar events.
5. Generate proposals and track project delivery after close.
6. Run campaigns for nurture or recovery; review reports and automation.

Lite

Core CRM: dashboard, leads, pipeline, contacts, companies, tasks, reports, basic settings.

Business

Adds calendar, proposals, projects, campaigns, and AI assistant.

Enterprise

Adds automation, team management, integrations, and audit log.

• Navigation items declare a minimum tier in lib/navigation.ts.
• FeatureGate and DemoPlanGuard hide or upgrade-prompt UI for locked features.
• Authenticated workspaces load plan from workspaces.plan_tier; owners can PATCH /api/workspace/plan.
• Server-side authorization uses RBAC permissions — plan gating is a product demo layer, not the security boundary.

nexcrm/
├── apps/web/                 # Next.js frontend (@nexcrm/web)
│   ├── src/app/              # Routes (marketing, auth, /app CRM)
│   ├── src/components/       # UI by domain
│   ├── src/data/schemas/     # Zod domain schemas
│   ├── src/lib/              # auth, ai, supabase, routes, documentation
│   ├── src/modules/          # Feature MVC modules
│   └── content/nexagent/     # NexAgent KB markdown chunks
├── packages/shared/          # @nexcrm/shared
├── supabase/migrations/      # SQL schema + RLS
├── PLAN/                     # PRDs and implementation handoffs
└── deploy/                   # VPS bootstrap, nginx

Features follow a scalable MVC layout under apps/web/src/modules/. Today most persistence is centralized in modules/crm/ with thin per-feature barrels re-exporting server actions.

modules/<feature>/
  model/           # Zod + view types
  application/     # Use cases (planned)
  infrastructure/  # Repositories + Supabase mappers
  interface/       # Server actions + queries
  presentation/    # Optional presenters

1. UI or CrmStoreProvider calls a server action.
2. Action calls requireWorkspaceScope() for tenant context.
3. Supabase client (lib/supabase/server) executes the query.
4. Result returns as RepositoryResult<T> ({ ok, data } | { ok: false, error }).
5. Client bridge (crm-store-supabase-bridge) syncs local store after mutations.

• Supabase Auth with SSR cookie sessions; profiles auto-created on signup.
• Workspace-first: every CRM row has workspace_id.
• Signup bootstraps a workspace and owner membership.
• Additional users join via email invitation (workspace_invitations) and accept at /invite.

1. Middleware (proxy.ts) — session required for /app/**
2. Server actions — workspace scope + permission checks (can, requirePermission)
3. Supabase RLS — is_active_workspace_member() on all CRM tables
4. UI — nav and plan gating (presentation only, not authorization)

AI in NexCRM is decision support, not autopilot. Every generation produces a draft that a human must approve, dismiss, or execute. When AI_FEATURES_ENABLED is false or no API key is set, mock generators provide deterministic fallback content.

# apps/web/.env.local
AI_FEATURES_ENABLED=true
AI_PROVIDER=auto          # auto | gemini
GEMINI_API_KEY=...
GEMINI_MODEL=gemini-2.0-flash

# Optional async workflows
N8N_WEBHOOK_BASE_URL=...
N8N_WEBHOOK_SECRET=...

1. User triggers generateAiDraftAction from an AI action surface.
2. Provider (Gemini or mock) returns structured content; job recorded in ai_jobs.
3. Draft stored in ai_drafts with status draft.
4. User approves (approveAiDraftAction), dismisses, or executes tied CRM mutation.
5. Usage tracked in ai_usage_events for cost controls.

NexAgent is a Business-tier floating widget in the app shell (not a separate route). It answers product how-to questions via markdown KB retrieval (apps/web/content/nexagent/), summarizes workspace CRM data, suggests navigation, and can trigger existing AI draft tools — always with human approval for writes.

• Widget: components/nexagent/ — mascot, chat panel, quick actions, draft cards.
• Agent loop: lib/nexagent/agent.ts — KB search, workspace snapshot, tool calls (navigate, search entities, run AI draft).
• Server actions: modules/nexagent/interface/nexagent.actions.ts.
• Tier-gated via isFeatureEnabled("assistant", plan); snooze and panel state persist in localStorage.

# From repo root
npm install
cp apps/web/.env.example apps/web/.env.local
# Fill in NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY
npm run dev    # http://localhost:3000

• Sign-up conversion — do not add friction to auth flows.
• Page load and interaction latency — keep dashboard snappy.
• AI cost per workspace — stay within cost-controls budgets.

• Full CRM UI shell with 20+ app pages
• Supabase schema, RLS, and central CRM server actions
• Auth middleware, workspace context, RBAC permission map
• AI draft pipeline (Gemini + mock fallback)
• Campaigns create/edit/delete with Supabase persistence
• NexAgent floating guide (KB retrieval, workspace tools, quick AI actions)
• Workspace plan_tier persistence and owner plan switcher
• Invitation accept flow at /invite
• Marketing documentation page at /documentation
• Plan-tier gating and Playwright smoke suite

• NexAgent v2 — expanded KB, richer tool orchestration (PLAN/nexagent-floating-guide)
• Full-page Assistant — still keyword mock; may converge with NexAgent later
• Projects — list and AI actions; create/edit/delete and milestone mutations planned
• Feature modules — barrels today; full per-feature MVC layers planned
• AI migration 004 — manual apply for persistence tables
• HeroUI v3 styling migration and UI/UX refresh

• apps/api backend service (BullMQ, Redis) — planned separately
• Real billing and payment integration — demo UI only
• Production email/SMS campaign delivery — orchestration UI only
• Mobile-native apps — responsive web first
• Custom per-tenant AI model fine-tuning