SalesOS

SalesOS is a reusable TypeScript operating layer for sales teams and sales-driven platforms.

It manages leads, lead scoring, pipelines, stages, deals, sales products, quotations, proposals, activities, forecasts, analytics, events, audit logs, and role-based permissions.

Run

npm run build
npm start

Open:

http://localhost:5300/health
http://localhost:5300/docs
http://localhost:5300/salesos/overview

Default tenant:

demo-tenant

Use headers:

x-tenant-id: demo-tenant
x-user-id: admin-user
x-role: sales_admin

Test

npm test

Main demo IDs

lead_asha
lead_rahul
lead_neha
pipe_default
stage_qualify
stage_discovery
stage_proposal
stage_negotiation
stage_won
stage_lost
deal_appneurox_northstar
deal_brandlyup_pixel
deal_acadnexus_school
prod_ai_setup
prod_growth_pack
prod_support_plan
quote_northstar
quote_pixel
prop_northstar
forecast_q2_inr

Example: create lead

curl -X POST http://localhost:5300/salesos/leads \
  -H "Content-Type: application/json" \
  -H "x-role: sales_admin" \
  -d '{"firstName":"Dev","lastName":"Sen","email":"dev@acme.example","company":"Acme Retail","source":"referral","expectedValue":250000,"tags":["enterprise","high-intent"]}'

Example: convert lead

curl -X POST http://localhost:5300/salesos/leads/lead_neha/convert \
  -H "Content-Type: application/json" \
  -H "x-role: sales_admin" \
  -d '{"title":"Pixel Studio GrowthOS Expansion","closeDate":"2026-07-15"}'

Example: create quote

curl -X POST http://localhost:5300/salesos/quotes \
  -H "Content-Type: application/json" \
  -H "x-role: sales_admin" \
  -d '{"dealId":"deal_appneurox_northstar","validUntil":"2026-06-30","lineItems":[{"productId":"prod_ai_setup","quantity":2,"discountPct":10},{"productId":"prod_support_plan","quantity":12}],"terms":"50% advance, 50% after launch"}'

Example: create forecast

curl -X POST http://localhost:5300/salesos/forecasts \
  -H "Content-Type: application/json" \
  -H "x-role: sales_admin" \
  -d '{"periodStart":"2026-05-01","periodEnd":"2026-06-30","currency":"INR"}'

Development structure

src/
 ├── core/
 ├── engines/
 ├── modules/
 ├── services/
 ├── seed-state.ts
 └── main.ts

Permissions

Role	Purpose
viewer	Read-only sales overview and analytics
sales_rep	Leads, deals, quotes, activities
sales_manager	Deal closing, quote approval, forecasting, audits
sales_ops	Pipelines, products, forecasting, audits
quote_manager	Quote approval and proposals
sales_admin/admin/owner	Full access
auditor	Read-only plus audit logs

OS integrations

GrowthOS → SalesOS       marketing qualified leads
SalesOS → ClientOS       account/customer history
SalesOS → FinanceOS      invoice after accepted quote
SalesOS → AnalyticsOS    dashboards and KPIs
SalesOS → AutomationOS   follow-up reminders and approvals
SalesOS → AIOS           AI lead scoring and proposal drafting
SalesOS → SecurityOS     RBAC and audit controls

For production, replace the JSON file store with PostgreSQL using database/schema.sql.

Planning Alignment

• Official package: @appneurox/salesos
• Manifest: manifest.json
• Domain API namespace: /v1/sales
• Modes: standalone and PlatformOS integrated
• Related systems: GrowthOS, FinanceOS

See docs/planning.md for the planning contract applied from APPNEURAL Plannings/OSs.