Engineering reference — v1 (2026)

Technical Documentation & Architecture

The complete source of truth for the MageTech Lead Intelligence platform: system architecture, technology stack, every module and function, every API input & output, role-permission matrix, key business flows and full configuration.

Why this document Architecture API reference
0
Frontend routes
0
REST endpoints
0
Roles
0
Permissions
Before you read

About this document

Who it is for, how it is organized, and why reading it saves hours of code archaeology.

🎯

What it contains

Everything needed to understand, run, extend and maintain the platform: architecture, stack, modules, endpoints with request/response shapes, business rules, security model and configuration.

👥

Who should read it

Developers (onboarding, integration, debugging), architects (design review, extension), QA (expected behaviors & status catalogs), product managers (feature map & capabilities), sysadmins (deployment & configuration).

🧭

How to use it

Read Architecture and Stack first. Jump to API for endpoint contracts, Modules for per-feature function detail, Flows for how data moves, and Reference for enums, security and configuration.

💡

Why it's useful

One canonical reference instead of digging through source. It answers “what should happen here?”, “which endpoint does that?”, “who is allowed?”, and “how is this configured?” in seconds.

3-tier
React SPA · REST API · Postgres
JWT
Stateless · 60 min access
14
Permission constants
38
LeadDto fields
System architecture

How the system is put together

Three clean tiers. The browser talks only to the Spring Boot API; the API owns all rules; PostgreSQL (with PGVector for AI search) is the single source of truth. Every record belongs to an organization (tenant).

Presentation

Next.js Frontend

React 19 SPA on Next 16 App Router (port 3000). Dark corporate theme, inline forms, ⌘K command palette, pure-CSS charts.

  • lib/api.ts — fetch client + token refresh
  • 21 routes under src/app
  • 26+ UI primitives (shadcn/Base UI)
Application

Spring Boot API

Java 21, REST under /api/v1 (port 8081). JWT security, RBAC enforced in services, Flyway migrations, scheduled campaign engine.

  • 24+ controllers across domains
  • @Scheduled campaign poll (60 s)
  • OpenAPI + Actuator exposed
Data

PostgreSQL + PGVector

Transactional core (JPA/Hibernate) plus vector embeddings for knowledge-base similarity search. Multi-tenant via organization_id.

  • Migrations V1 → V6+
  • PGvector(1536) embedding column
  • JSONB analysis & step payloads

Animated shuttle = one authenticated API call (browser → API → DB → back)

Request lifecycle

What happens on every request

One end-to-end round trip, from keyboard to database.

1
Browser

Client call

Frontend builds the URL via lib/api.ts → http://localhost:8081/api/v1/… and attaches Authorization: Bearer <accessToken> (from localStorage).

2
Edge

Security filter chain

Spring Security (stateless, CSRF off) permits public paths (/auth/register|login|refresh, /webhooks/**, Swagger, Actuator health) and authenticates everything else.

3
Auth

JWT validation

JwtAuthenticationFilter parses the Bearer token, checks signature + expiry, and loads authorities: ROLE_<ROLE> plus each granted PERM_<PERMISSION>.

4
Controller

Routing & validation

The @RestController maps path, binds and validates the DTO, then forwards to the service — controllers stay thin.

5
Service

Authorization + business rules

Services explicitly check permissions (e.g. LEADS_WRITE). All domain rules live here: role promotions, campaign guards, reply auto-suppression.

6
Repository

Persistence

Spring Data JPA repositories, scoped by organization_id, hit PostgreSQL; @Transactional keeps operations atomic and audit events are recorded.

7
Response

Back to the client

DTOs (never entities) return as JSON. Errors use one shape: { error, message, timestamp, status }. On a 401, lib/api.ts transparently refreshes and retries once.

Technology stack

Versions, libraries & configuration

Exact versions as declared in backend/pom.xml and frontend/package.json.

🧩

Backend — Spring Boot 3

  • • Java 21 · Maven mvnw.cmd
  • • Spring Web, Security, Data JPA, Validation, Actuator
  • • PostgreSQL + PGVector (embeddings)
  • • Flyway migrations V1–V6
  • • Apache POI + Commons CSV (import parsing)
  • • OpenAPI / Swagger UI
  • • Optional OpenAI (gpt-4o-mini, text-embedding-3-small)
  • • @Scheduled campaign engine (60 s poll)
⚛️

Frontend — Next.js 16

  • • Next 16.3.5 App Router · Turbopack
  • • React 19.2.8 · TypeScript ^5 (strict)
  • • Tailwind CSS v4 (CSS-first, no config file)
  • • shadcn/ui + @base-ui/react primitives
  • • lucide-react icons · cmdk (⌘K palette)
  • • Custom fetch client (lib/api.ts), no React Query
  • • AuthProvider context + localStorage tokens
  • • Charts hand-built in pure CSS (no chart lib)
🖥

Runtime & infrastructure

  • • Backend: http://localhost:8081 (SERVER_PORT)
  • • Frontend dev: http://localhost:3000
  • • Apache httpd on 8080 (leave running)
  • • CORS: backend allows localhost:3000
  • • Env: DB_PASSWORD, JWT_SECRET, NEXT_PUBLIC_API_URL
  • • Restart backend via mvnw.cmd spring-boot:run
API reference

Every endpoint, input & output

All endpoints live under /api/v1. Paginated lists return PageResponse<T> = { items, totalItems, totalPages, currentPage, pageSize }; plain collections return T[]. Errors always come as { error, message, timestamp, status }.

MethodEndpointPurposeInput → Output
POST/auth/registerCreate org + first user{organizationName, firstName, lastName, email, password} → 201 AuthResponse. Creates the workspace Owner.
POST/auth/loginSign in{email, password} → AuthResponse (user, accessToken, refreshToken, expiresInSeconds, tokenType).
POST/auth/refreshRotate tokens{refreshToken} → new AuthResponse. Refresh TTL 7 days.
GET/auth/meCurrent profile→ UserDto.
GET/usersList members→ UserDto[].
POST/usersCreate memberCreateUserRequest → 201 UserDto. OWNER/ADMIN only; only OWNER may grant OWNER/ADMIN.
PUT/users/{id}Update memberUpdateUserRequest (incl. role) → UserDto. Cannot change your own role/active.
DELETE/users/{id}Deactivate member→ 204. Guards: no self-deactivation, last owner protected.
MethodEndpointPurposeInput → Output
GET/leadsPaged lead list?page,size,q,country,industryId,status,emailStatus,tagId,segmentId,companyId,leadSourceId,fromDate,toDate → PageResponse<LeadDto> (38 fields, sort createdAt DESC).
GET/leads/{id}Lead detail→ LeadDto (technologies, tags, segments included).
POST/leadsCreate leadCreateLeadRequest (needs email OR companyName; duplicate email → 400) → 201 LeadDto.
PUT/leads/{id}Update leadUpdateLeadRequest (all optional) → LeadDto.
DELETE/leads/{id}Delete lead→ 204. Blocked 409 while enrolled in active campaigns.
POST/leads/{id}/tags/{tagId}Add tag→ LeadDto. DELETE variant removes.
POST/leads/{id}/segments/{segmentId}Add to segment→ LeadDto. DELETE variant removes.
GET/leads/{id}/rawRaw import payloads→ LeadRawDataDto[].
GET/leads/{id}/campaignsCampaign membership→ CampaignRefDto[] (drives the delete-guard UI).
ALL/tags, /lead-sources, /segmentsTags & segments CRUDGET list / POST create / PUT (tags) / DELETE → respective DTOs.
MethodEndpointPurposeInput → Output
GET/companiesPaged companies?page,size,q → PageResponse<CompanyDto>.
GET/companies/{id}Company detail→ CompanyDetailDto = company + domains[] + technologies[] + leadCount.
POST/companiesUpsert companyCompanyUpsertRequest → 201 CompanyDto (find-or-create by domain → name).
PUT/companies/{id}Update companyCompanyUpsertRequest → CompanyDto.
DELETE/companies/{id}Delete company→ 204. Blocked 409 while leads are linked.
GET/companies/{id}/campaignsCampaign membership→ CampaignRefDto[].
GET/meta/industries · /meta/technologies · /meta/countriesReference data→ industries/technologies as {id,name[,category]}, countries as strings.
GET/meta/statusesEnum catalog→ {leadStatuses[], emailStatuses[]} — powers filter dropdowns.
MethodEndpointPurposeInput → Output
POST/imports/uploadUpload CSV/XLSXmultipart file (xlsx/csv, ≤50 MB) → ImportBatchDto (status PARSED). Max 200k rows.
GET/importsImport history→ PageResponse<ImportBatchDto>.
GET/imports/{id}/mappingGet column mapping→ MappingResponse (sourceColumns, targetFields, suggestedMapping, unmappedSourceColumns).
PUT/imports/{id}/mappingSave mapping{column→field} → MappingResponse; batch → MAPPED.
GET/imports/{id}/previewPreview rows?offset,limit (limit ≤ 500) → PreviewResponse (columns + mapped rows).
GET/imports/{id}/duplicatesDuplicate review→ DuplicateResponse — groups keyed by DB lead with suggested action; batch → DUPLICATE_REVIEW.
POST/imports/{id}/confirmCommit import{mapping, duplicateDecisions} with actions IMPORT / MERGE / IGNORE → ImportResult (imported, merged, ignored, error, invalidEmail counts).
GET/imports/{id}/errorsRow errors→ PageResponse<ImportErrorDto>.
DELETE/imports/{id}Cancel import→ ImportBatchDto (CANCELLED).
MethodEndpointPurposeInput → Output
GET/campaignsList campaigns?page,size,status → PageResponse<CampaignDto> (sort updatedAt DESC).
POST/campaignsCreate campaignCampaignRequest {name, description, sequence[], targetFilter} → CampaignDto (DRAFT).
PUT/campaigns/{id}Update campaignCampaignRequest → CampaignDto. Blocked while ACTIVE.
DELETE/campaigns/{id}Delete campaign→ 204. Blocked while ACTIVE.
POST/campaigns/{id}/startActivateRequires ≥ 1 step; DRAFT → ACTIVE + startedAt.
POST/campaigns/{id}/pausePauseACTIVE → PAUSED.
POST/campaigns/{id}/resumeResumePAUSED → ACTIVE.
POST/campaigns/{id}/completeCompleteACTIVE → COMPLETED + completedAt.
POST/campaigns/{id}/leadsAdd leads{leadIds[], filter} → {added, skipped}. Leave ACTIVE to edit.
GET/campaigns/{id}/leadsEnrolled leads→ PageResponse<CampaignLeadDto> (per-lead step + status).
GET/campaigns/{id}/metricsHealth metrics→ CampaignMetrics {totalLeads, pending, sent, opened, replied, bounced, unsubscribed, failed, skipped}.
DELETE/campaigns/{id}/leads/{cid}Remove enrollee→ 204.
ALL/templatesEmail template CRUDGET/POST/PUT/DELETE + /duplicate + /preview (missing variables) + /generate (AI draft from a lead).
MethodEndpointPurposeInput → Output
GET/messagesOutbound messages?campaignId,leadId → PageResponse<EmailMessageDto> (sort sentAt DESC).
GET/repliesInbound replies→ PageResponse<ReplyDto>.
POST/repliesRecord reply (manual)ReplyCreateRequest → ReplyDto. Triggers suppression + campaign/lead updates + maybe opportunity.
POST/webhooks/emailsEmail webhook (reply)WebhookEmailRequest matched to an outbound message by providerMessageId / inReplyTo → ReplyDto. 400 if unmatched.
POST/webhooks/emails/openOpen event{providerMessageId} → {ok, messageId}; marks OPENED.
POST/webhooks/emails/bounceBounce event{providerMessageId} → {ok, messageId}; marks BOUNCED + suppresses.
GET/suppressionSuppression list?page,size → PageResponse<SuppressionDto>.
POST/suppressionAdd suppression{emails[], reason} → SuppressionDto.
DELETE/suppression/{id}Remove entry→ 204.
ALL/kb/documentsKnowledge docs CRUDGET/POST/PUT/DELETE → KnowledgeDocumentDto; embedded on create/update.
POST/kb/searchVector search{query, limit} → KnowledgeDocumentDto[], ordered by embedding cosine distance.
POST/kb/askGrounded Q&A{question, leadId?, companyId?} → AskResponse {answer, sources[], model}.
MethodEndpointPurposeInput → Output
GET/crm/opportunitiesOpportunity list?stage → PageResponse<OpportunityDto>.
GET/crm/opportunities/pipelinePipeline summary→ PipelineSummary (per-stage count + value + totals).
ALL/crm/opportunities[/{id}]Opportunity CRUDPOST/PUT/DELETE → OpportunityDto; stage changes write events + sync lead status.
GET/crm/opportunities/{id}/eventsRecorded events→ OpportunityEventDto[] (CREATED / STAGE_CHANGE / NOTE).
ALL/crm/meetings[/{id}]Meeting CRUDGET + /upcoming; POST/PUT/DELETE → MeetingDto (PENDING/CONFIRMED/CANCELLED/DONE).
ALL/crm/proposals[/{id}]Proposal CRUDProposalRequest incl. line items. Editable only while DRAFT; edits bump version.
POST/crm/proposals/{id}/statusProposal status{status} — SENT → opp PROPOSAL_SENT; ACCEPTED → opp WON 100%; REJECTED → opp LOST 0%.
ALL/abm/accounts[/{id}]ABM targets CRUDPOST/PUT/DELETE → AbmAccountDto (tier TARGET / KEY / STRATEGIC).
GET/abm/suggestionsScored suggestions?limit=N → AbmSuggestionDto[] ranked by fitScore.
MethodEndpointPurposeInput → Output
POST/ai/leads/{leadId}/intelligenceRun AI analysis→ LeadIntelligenceResult: score (0–100), summary, signals[], recommendedServices[], suggestedAngle, riskNotes[], model, analyzedAt.
GET/ai/leads/{leadId}/intelligenceLatest analysis→ newest result, or computes one on demand.
GET/ai/analysesAnalysis history→ PageResponse<AiAnalysis>.
GET/analytics/dashboardDashboard KPIs→ DashboardStats: KPIs + byStatus/byCountry/byIndustry/byTechnology + recentImports.
GET/integrations/statusConnector status→ {provider → boolean} (HUBSPOT / SALESFORCE / SIMULATED).
POST/integrations/{provider}/syncPush lead(s){leadIds?} (default top 100 by org) → {provider, pushedLeads}.
GET/organizations/meWorkspace profile→ org details. PUT {name} → renamed org (ORG_WRITE).
ALL/magentech-services[/{id}]Services catalogGET ?activeOnly=true; POST/PUT/DELETE → MageServiceDto.
ALL/playbooks[/{id}]Sales playbooksPlaybookRequest with steps [{title, guidance, templateId?, waitDays}] → PlaybookDto.
Functional detail

Every module — what it does, what goes in, what comes out

Per-module purpose, features and explicit input → output contracts. This is the “in and out” reference for features.

📊 Dashboard & Analytics

ReadGET /analytics/dashboard

Single aggregation endpoint powering the home screen, computed live from lead/company tables. Returns an empty structure when there is no data.

Input
  • Authenticated org (no parameters)
  • Read permission implied
Output
  • KPIs: totalLeads, validEmails, invalidEmails, suppressedEmails, totalCompanies, importedLeads, duplicateLeads
  • Distributions: byStatus, byCountry, byIndustry, byTechnology
  • recentImports (last 30 days, daily)

👤 Auth & Identity

Public/auth/*

Registration bootstraps one organization plus the founding Owner. Login issues a JWT access token (60 min) and a 7-day refresh token. Deactivated users cannot sign in.

Input
  • register: org name, profile, email, password (10–100 chars)
  • login: email + password (BCrypt strength 12)
Output
  • AuthResponse: UserDto + accessToken + refreshToken + expiresInSeconds
  • JWT claims: sub=userId, org, role

🧑‍💼 Team & Roles

Admin/users · /organizations

Member lifecycle: invite, change role, deactivate. Hard rules: only OWNER creates/promotes OWNER/ADMIN; no self-deactivation; the last active owner is always protected.

Input
  • CreateUserRequest (email, name, role)
  • UpdateUserRequest (role / active)
Output
  • UserDto list / single
  • Org rename via PUT /organizations/me

📇 Leads

Core/leads

The central record: a 38-field DTO spanning contact, employment, company, location, enrichment (technologies, SEO), tags, segments and pipeline status. Delete is guarded against active-campaign enrollment.

Input
  • CreateLeadRequest — requires email OR companyName
  • Filters: q, country, industryId, status, emailStatus, tagId, segmentId, companyId, fromDate…
Output
  • LeadDto (38 fields) or PageResponse
  • Raw import payloads and campaign memberships

🏢 Companies

Core/companies

Account profiles de-duplicated by domain, enriched with technology signals and lead counts. Cannot be deleted while leads still reference it.

Input
  • CompanyUpsertRequest (profile, location, sizing, insights)
Output
  • CompanyDto list
  • CompanyDetailDto: + domains[], technologies[] (with source), leadCount

📥 Import Pipeline

Wizard/imports

Guided 5-stage wizard: upload → map → preview → review duplicates → confirm. Parses xlsx/csv (≤50 MB, ≤200k rows), auto-suggests the column mapping, and produces a complete audit trail of imported / merged / ignored / errored rows.

Input
  • Multipart file (xlsx/csv)
  • Column mapping {source→target}
  • Per-row duplicate decisions: IMPORT | MERGE | IGNORE
Output
  • ImportResult: totalRows, importedRows, mergedRows, ignoredRows, errorRows, invalidEmailRows
  • Row-level ImportError list
  • New leads land as IMPORTED; merged rows are marked duplicate and backfill missing fields

🚀 Campaigns

Scheduled/campaigns

Multi-step email campaigns with template sequences and wait days. A 60-second scheduled poll advances each active campaign's due pending leads. Editing / deleting / adding leads is locked while ACTIVE (pause first).

Input
  • CampaignRequest {name, description, sequence[{templateId, waitDays}], targetFilter}
  • State actions: start / pause / resume / complete
  • Add leads via leadIds or a target filter
Output
  • CampaignDto + metrics {totalLeads, pending, sent, opened, replied, bounced, unsubscribed, failed, skipped}
  • CampaignLeadDto[] per-enrollee progress

✉️ Email Engine — Messages, Replies, Suppression

Delivery/messages · /replies · /webhooks · /suppression

Outbound sends run through a provider abstraction (default SIMULATED). Inbound replies and open/bounce events arrive via webhooks and update the whole graph: reply → suppress sender, mark campaign/lead REPLIED, and auto-create an opportunity.

Input
  • Webhook events: emails (reply), emails/open, emails/bounce
  • Manual ReplyCreateRequest
  • Suppression {emails[], reason}
Output
  • EmailMessageDto / ReplyDto records
  • Suppression entries (sources: MANUAL, BOUNCE, COMPLAINT, UNSUBSCRIBE, IMPORT)
  • Lead → REPLIED; opportunity auto-created when enabled

🤖 AI Intelligence

LLM/ai

Per-lead analysis: an LLM path (gpt-4o-mini, temperature 0.3, strict JSON) with a deterministic rule-based fallback so scoring always works even without a key. Results are persisted as AiAnalysis (JSONB) and drive the score badges (0–39 low, 40–69 medium, 70–84 good, 85–100 excellent).

Input
  • leadId (optionally re-run)
  • Fallback rules: valid email +30, website +10, employees +10, industry +10, country +10, tech +10, SEO +10, commerce tech +10
Output
  • LeadIntelligenceResult: score, summary, signals[], recommendedServices[] (top 5 with score & reasoning), suggestedAngle, riskNotes[], model, analyzedAt

📚 Knowledge Base

RAG/kb

Documents are embedded (OpenAI text-embedding-3-small, 1536 dims; deterministic hash fallback) into PGVector. Search runs cosine similarity (ORDER BY embedding <=> vector); ask retrieves top-4 docs and returns a grounded answer with sources.

Input
  • Document {title, content, sourceType, tags}
  • search {query, limit}
  • ask {question, leadId?, companyId?}
Output
  • KnowledgeDocumentDto (includes distance)
  • AskResponse: answer, sources[], model

💼 CRM — Opportunities, Meetings, Proposals

Pipeline/crm

Full pipeline: opportunities with stage / value / probability / expected close, activity events, meetings (PENDING → CONFIRMED → DONE), and proposals with line items. Stage and proposal changes cascade into lead-status synchronization.

Input
  • OpportunityRequest (stage, value, owner, nextAction…)
  • Proposal {status} transitions; meeting upserts
Output
  • OpportunityDto / PipelineSummary / events[]
  • Cascade: WON → lead WON · LOST → lead LOST · ACCEPTED → opp WON (100%)

🎯 ABM

Accounts/abm

Account-based marketing: target accounts tiered TARGET / KEY / STRATEGIC with budgets, owners, and AI suggestions ranked by the same fit-scoring signals.

Input
  • AbmForm {company, tier, budget, score, notes}
  • suggestions?limit=N
Output
  • AbmAccountDto CRUD
  • AbmSuggestionDto[] {company, industry, leadCount, technologyCount, fitScore}

🔌 Integrations

Connectors/integrations

SPI-based CrmConnector with three providers. HUBSPOT and SALESFORCE activate when their tokens are configured; SIMULATED is always available for demos. Sync pushes lead data out to the CRM.

Input
  • {provider}/sync with optional leadIds (default top 100)
Output
  • {provider: available} status map
  • {provider, pushedLeads} sync result

🧩 Templates, Playbooks & Services Catalog

Content/templates · /playbooks · /magentech-services

Reusable content layer: email templates with {{variables}} and AI generation, sales playbooks with guided steps and wait days, and the services catalog the AI uses to recommend offerings.

Input
  • TemplateRequest {name, category, subject, body, variables}
  • PlaybookRequest with steps
  • template/generate {leadId, tone, goal, language}
Output
  • TemplatePreview {subject, body, missingVariables[]}
  • AI-drafted EmailTemplateDto
  • PlaybookDto / MageServiceDto CRUD
Business flows

How data actually moves

End-to-end behaviors: import, lead lifecycle, campaign execution, replies and AI scoring.

1 · Import pipeline stages

UPLOADED→ PARSED→ MAPPED→ VALIDATED→ DUPLICATE_REVIEW→ CONFIRMED→ COMPLETED
FAILED CANCELLED

Duplicate detection order: email → LinkedIn URL → company domain → company + contact. Parsers: Apache POI (xlsx) + Commons CSV; maximum 200k rows per file.

2 · Lead lifecycle

IMPORTED→ NEW→ VALIDATED→ CONTACTED→ REPLIED→ QUALIFIED→ MEETING→ PROPOSAL→ NEGOTIATION
WON ✓ LOST ✗ ARCHIVED

Status is advanced automatically: import → IMPORTED; campaign send → CONTACTED; reply → REPLIED; CRM stages sync QUALIFIED / PROPOSAL / NEGOTIATION / WON / LOST back to the lead.

3 · Campaign execution (scheduled pump)

⏲
Every 60 s

Scheduler wakes

@Scheduled(fixedDelayString="${app.campaign.poll-millis:60000}", initialDelay=15000) scans ACTIVE campaigns.

🔍
Due filter

Find due enrollees

Pending CampaignLeads whose nextStepAt <= now and current step index is below the sequence length.

✉️
Send

Deliver the current step

Missing template or email → FAILED; suppressed or empty recipient → SKIPPED; success → SENT, step + 1, nextStepAt = now + waitDays · 86400s.

🏁
Finish

Sequence exhausted

After the last step is sent, nextStepAt is cleared and the enrollee becomes idle.

4 · Reply processing (webhook → effects)

Webhook / manual POST→ Match outbound msg→ Create Reply→ Suppress sender→ CampaignLead → REPLIED→ Lead → REPLIED→ Auto-create Opportunity

Auto-opportunity only when enabled (app.crm.auto-create-opportunity-on-reply=true) and no open opportunity exists for the lead yet.

5 · AI scoring (the rule fallback guarantees an answer)

analyzeLead(leadId)→ LLM configured?
Yes → gpt-4o-mini⇄ Strict JSON parse
No / parse fail → rules→ Score 0–100→ Persist AiAnalysis→ Return result

6 · CRM stage → default probability & lead sync

Opportunity stageDefault probabilityLead status sync
NEW10%—
QUALIFIED20%→ QUALIFIED
PROPOSAL_SENT40%→ PROPOSAL
NEGOTIATION60%→ NEGOTIATION
WON100%→ WON
LOST0%→ LOST
Reference

Enums, security, database & configuration

The canonical value catalog, role-permission matrix, data model and run configuration.

⚙️

Status enums

EnumValues
LeadStatusIMPORTED · NEW · VALIDATED · CONTACTED · REPLIED · QUALIFIED · MEETING · PROPOSAL · NEGOTIATION · WON · LOST · ARCHIVED
EmailStatusUNKNOWN · VALID · INVALID · RISK · SUPPRESSED · DUPLICATE · BOUNCED · UNSUBSCRIBED
CampaignStatusDRAFT · ACTIVE · PAUSED · COMPLETED
CampaignLeadStatusPENDING · SENT · OPENED · REPLIED · BOUNCED · UNSUBSCRIBED · FAILED · SKIPPED
MessageStatusSENT · DELIVERED · OPENED · CLICKED · BOUNCED · FAILED
ImportStatusUPLOADED · PARSED · MAPPED · VALIDATED · DUPLICATE_REVIEW · CONFIRMED · COMPLETED · FAILED · CANCELLED
OpportunityStageNEW · QUALIFIED · PROPOSAL_SENT · NEGOTIATION · WON · LOST
ProposalStatusDRAFT · SENT · ACCEPTED · REJECTED
MeetingStatusPENDING · CONFIRMED · CANCELLED · DONE
SuppressionSourceMANUAL · BOUNCE · COMPLAINT · UNSUBSCRIBE · IMPORT
AbmTierTARGET · KEY · STRATEGIC
RoleOWNER · ADMIN · SALES_MANAGER · SALES_USER · VIEWER
🛡️

Roles & permissions

5 roles × 14 permission constants. JWT authorities: ROLE_<ROLE> + one PERM_<PERMISSION> each.

RoleGranted permissions
OWNERAll (incl. USERS_WRITE, ORG_WRITE, promotes admins)
ADMINAll permissions
SALES_MANAGERLEADS_R/W/D · IMPORTS_R/W · COMPANIES_R/W · SEGMENTS_R/W · USERS_READ · ORG_READ
SALES_USERLEADS_R/W · IMPORTS_READ · COMPANIES_READ · SEGMENTS_R/W · USERS_READ
VIEWERLEADS_READ · IMPORTS_READ · COMPANIES_READ · SEGMENTS_READ · USERS_READ · ORG_READ

Constants: LEADS_READ · LEADS_WRITE · LEADS_DELETE · IMPORTS_READ · IMPORTS_WRITE · COMPANIES_READ · COMPANIES_WRITE · SEGMENTS_READ · SEGMENTS_WRITE · USERS_READ · USERS_WRITE · ORG_READ · ORG_WRITE · AUDIO_READ.

  • • Only OWNER may grant OWNER/ADMIN roles
  • • Cannot deactivate or demote yourself
  • • The last active owner is always protected
  • • Deactivated users cannot sign in
🗄️

Database & migrations

Multi-tenant JPA: every table carries organization_id. Base hierarchy: BaseEntity (id, created_at, updated_at) → BaseOrgEntity (+ organization_id). Embeddings live in a PGvector(1536) column; AI results and campaign steps use JSONB.

MigrationContent
V1__core.sqlorganizations, users, leads, tags, companies, raw data, reference data
V2__phase2_services_ai.sqlmage services + AI analysis tables
V3__phase3_campaigns.sqltemplates, campaigns, campaign_leads, messages, replies, suppression
V4__phase4_crm.sqlopportunities, events, meetings, proposals
V5__phase5_ai_kb_abm.sqlknowledge documents + PGVector, ABM accounts
V6__fix_opportunity_event_updated_at.sqladds updated_at to opportunity_event
🧾

Configuration

KeyDefault / value
SERVER_PORT8081
DB_PASSWORDPostgreSQL password (env)
JWT_SECRET≥ 32 bytes (env); access 60 min, refresh 7 days
app.campaign.poll-millis60000 (initial delay 15000)
app.crm.auto-create-opportunity-on-replytrue
app.integrations.hubspot-token / salesforce-*enable real connectors
app.uploads.dirper-org import file storage
ai.* (OpenAI)gpt-4o-mini · text-embedding-3-small
NEXT_PUBLIC_API_URLhttp://localhost:8081

Run backend: mvnw.cmd spring-boot:run with JAVA_HOME (JDK 21), DB_PASSWORD, JWT_SECRET and SERVER_PORT=8081 set.

Pricing & billing model

Usage-aware plans

Pricing is modeled as a workspace that bundles capacity — leads, AI analyses (scoring, recommendations, email generation, KB Q&A), enrichment and campaign contacts — rather than purely per-seat licensing. Users are simply a secondary constraint. This section documents the proposed plan tiers, the intended billing & subscription module, and migration approach.

Prices in USD. Annual plans billed once per year. CTA buttons are placeholders pending the Billing module.

Starter

$49/mo · annual $39/mo
Import pipeline + enrichment (limited)

$49/mo

2
Users
2.5K
Leads
250
AI / mo
View model
MOST POPULAR

Growth

$149/mo · annual $119/mo
Full AI outreach + campaigns + CRM + HubSpot sync

$149/mo

5
Users
15K
Leads
2K
AI / mo
View model

Professional

$399/mo · annual $319/mo
Adds Salesforce + API + ABM

$399/mo

15
Users
50K
Leads
10K
AI / mo
View model

Enterprise

Custom pricing
SSO · dedicated tenant · SLA · custom limits

Custom/ contact sales

∞
Users
∞
Leads
∞
AI usage
View model

Plan tiers — feature matrix

CapabilityStarterGrowthProfessionalEnterprise
Users2515Unlimited
Lead capacity2,50015,00050,000Custom
AI analyses / mo2502,00010,000Custom
AI emails / mo1001,0005,000Custom
Active campaigns320UnlimitedUnlimited
Campaign leads1,00010,00050,000Custom
Lead imports / CSV / Excel✓✓✓✓
Email validation✓✓✓✓
Company enrichmentLimited✓✓✓
AI recommendations✓✓✓✓
Knowledge base10 docs100 docs1,000 docsCustom
AI knowledge Q&A✓✓✓✓
CRM — opportunities / meetings / proposals✓✓✓✓
ABM—✓✓✓
HubSpot integration—✓✓✓
Salesforce——✓✓
API access——✓✓
Advanced analytics—✓✓✓
Audit trail✓✓✓✓
Priority support—✓✓Dedicated
SSO———✓
Dedicated tenant———✓

Add-ons (usage spikes, no forced upgrade)

Add-onTier 1Tier 2Tier 3
Additional leads+10,000 · $29+50,000 · $99+100,000 · $169
AI credits+1,000 analyses · $19+5,000 analyses · $69+10,000 analyses · $119
Enrichment+5,000 enrichments · $29+25,000 enrichments · $99+100,000 enrichments · $299
Campaign contacts+10,000 contacts · $19+50,000 contacts · $69+100,000 contacts · $119

Local pricing — India (INR)

GST extra where applicable.

PlanMonthly (INR)Annual (INR)
Starter₹3,999₹39,990 / year
Growth₹11,999₹119,990 / year
Professional₹31,999₹319,990 / year
EnterpriseCustomCustom

🚀 14-day free trial

No credit card required. Seeded with a fixed quota, no plan selected.

100
Leads
50
AI analyses
25
AI emails
1
Campaign
1
User
Basic
CRM

🧾 Billing & Subscription module

⚠ PROPOSED — NOT YET IMPLEMENTED

Not present in the current codebase. Recommended future module so the documented plans can be enforced and invoiced. The current system has no plan limits — enrichment, AI quotas and campaign allowances are not yet gated.

1 · Subscription

organization_id → plan tier (STARTER / GROWTH / PROFESSIONAL / ENTERPRISE), billing period (monthly / annual), start & renewal dates, soft limit overrides for add-ons.

➜

2 · Usage Meter

Counters per organization + period: AI analyses (scoring, recommendations, emails, KB Q&A), imported leads, enrichment calls, campaign contacts. Incremented at write-time in existing services.

➜

3 · Invoices

Records invoice, add-on line items (override allowances) and amount. Optional webhook to a payment provider; invoice stores provider reference.

➜

4 · Limit Enforcement

Checked inside campaign scheduler, AI services, import pipeline and CRM actions. Hard vs soft limits: soft → warn, hard → block with 402-style error payload.

➜

Consumers

Leads (import + enrichment) · AI (scoring / email / Q&A) · Campaigns (contacts, sends). Enforcement surfaces in the API as QUOTA_EXCEEDED.

  • • Migration: single Flyway migration V7__billing.sql → subscriptions, usage_counters, invoices, plan_tiers (seeded reference data).
  • • Authz: read via existing multi-tenant pattern (BaseOrgEntity); plan changes restricted to OWNER.
  • • Trial: on registration, create a 14-day TRIAL subscription with fixed quota; conversion swaps tier and resets period counters.
  • • Pricing philosophy: workspace capacity model — leads / AI / enrichment / campaign contacts — with add-ons for temporary spikes (no forced plan upgrades).