AnalyticsOS

AnalyticsOS is a reusable analytics operating layer for Appneural-style platforms. It handles data sources, ingestion, metric definitions, KPI evaluation, dashboards, reports, CSV/JSON export, alerts, audit logs, and system events.

This starter is intentionally dependency-light. It uses TypeScript and Node.js built-in HTTP APIs only, so it can run without installing Express, NestJS, Prisma, or any external package. You can later migrate the modules to NestJS, PostgreSQL, Prisma, queues, and a full data warehouse.

What is included

AnalyticsOS
├── Data Source Module
├── Record Ingestion Module
├── Record Query Module
├── Metric Module
├── KPI Module
├── Dashboard Module
├── Report Module
├── Alert Module
├── Export Module
├── Events Module
├── Audit Module
├── Aggregation Engine
├── KPI Engine
├── Export Engine
└── PostgreSQL schema example

Requirements

• Node.js 20+
• TypeScript compiler available as tsc

No npm dependencies are required.

Run

cd analyticsos-complete
npm run build
npm start

API starts on:

http://localhost:4100

Health endpoint:

curl http://localhost:4100/health

Docs endpoint:

curl http://localhost:4100/docs

Test

npm test

Seed data

AnalyticsOS auto-seeds demo data on first run.

Demo tenant:

demo-tenant

Demo sources:

src_commerceos
src_websiteos
src_clientos

Demo metric IDs / keys:

metric_total_revenue      / total_revenue
metric_order_count        / order_count
metric_avg_order_value    / average_order_value
metric_total_sessions     / total_sessions
metric_total_conversions  / total_conversions
metric_support_tickets    / support_tickets

Demo dashboard:

dash_executive

Demo report:

report_monthly_performance

Manual reset:

npm run reset

Headers

AnalyticsOS uses simple headers for tenant and role simulation.

x-tenant-id: demo-tenant
x-user-id: user_001
x-role: owner | admin | analyst | executive | operator | viewer

Example:

-H "x-role: analyst" -H "x-tenant-id: demo-tenant"

Common API examples

1. View overview

curl -s http://localhost:4100/analyticsos/overview \
  -H "x-role: viewer" \
  -H "x-tenant-id: demo-tenant"

2. Run an ad hoc query

Revenue by channel for completed orders:

curl -s -X POST http://localhost:4100/analyticsos/query \
  -H "Content-Type: application/json" \
  -H "x-role: analyst" \
  -H "x-tenant-id: demo-tenant" \
  -d '{
    "entity": "order",
    "aggregation": "sum",
    "field": "metrics.revenue",
    "filters": [
      { "field": "dimensions.status", "operator": "eq", "value": "completed" }
    ],
    "groupBy": ["dimensions.channel"]
  }'

3. Calculate a saved metric

curl -s -X POST http://localhost:4100/analyticsos/metrics/metric_total_revenue/calculate \
  -H "Content-Type: application/json" \
  -H "x-role: viewer" \
  -H "x-tenant-id: demo-tenant" \
  -d '{"groupBy":["dimensions.channel"]}'

4. Evaluate a KPI

curl -s -X POST http://localhost:4100/analyticsos/kpis/kpi_monthly_revenue/calculate \
  -H "Content-Type: application/json" \
  -H "x-role: viewer" \
  -H "x-tenant-id: demo-tenant" \
  -d '{}'

5. Render a dashboard

curl -s -X POST http://localhost:4100/analyticsos/dashboards/dash_executive/render \
  -H "Content-Type: application/json" \
  -H "x-role: viewer" \
  -H "x-tenant-id: demo-tenant" \
  -d '{}'

6. Generate a report

curl -s -X POST http://localhost:4100/analyticsos/reports/report_monthly_performance/generate \
  -H "Content-Type: application/json" \
  -H "x-role: executive" \
  -H "x-tenant-id: demo-tenant" \
  -d '{}'

7. Export a report as CSV

curl -s -X POST http://localhost:4100/analyticsos/exports \
  -H "Content-Type: application/json" \
  -H "x-role: analyst" \
  -H "x-tenant-id: demo-tenant" \
  -d '{
    "targetType": "report",
    "targetId": "report_monthly_performance",
    "format": "csv"
  }'

8. Ingest records

curl -s -X POST http://localhost:4100/analyticsos/records/bulk \
  -H "Content-Type: application/json" \
  -H "x-role: operator" \
  -H "x-tenant-id: demo-tenant" \
  -d '{
    "records": [
      {
        "sourceId": "src_commerceos",
        "entity": "order",
        "timestamp": "2026-05-15T10:00:00.000Z",
        "dimensions": {
          "channel": "online",
          "region": "south",
          "product": "AI Starter Plan",
          "status": "completed"
        },
        "metrics": {
          "revenue": 25000,
          "orders": 20,
          "customers": 18
        }
      }
    ]
  }'

9. Create a custom metric

curl -s -X POST http://localhost:4100/analyticsos/metrics \
  -H "Content-Type: application/json" \
  -H "x-role: analyst" \
  -H "x-tenant-id: demo-tenant" \
  -d '{
    "key": "mobile_revenue",
    "name": "Mobile Revenue",
    "entity": "order",
    "aggregation": "sum",
    "field": "metrics.revenue",
    "format": "currency",
    "filters": [
      { "field": "dimensions.channel", "operator": "eq", "value": "mobile" },
      { "field": "dimensions.status", "operator": "eq", "value": "completed" }
    ],
    "defaultGroupBy": ["dimensions.product", "dimensions.region"]
  }'

10. Evaluate alerts

curl -s -X POST http://localhost:4100/analyticsos/alerts/evaluate \
  -H "Content-Type: application/json" \
  -H "x-role: analyst" \
  -H "x-tenant-id: demo-tenant" \
  -d '{}'

The seeded alert_support_high rule triggers because seeded support tickets are above its threshold.

API map

GET    /health
GET    /docs
GET    /analyticsos/overview

GET    /analyticsos/data-sources
POST   /analyticsos/data-sources
GET    /analyticsos/data-sources/:id
PUT    /analyticsos/data-sources/:id
DELETE /analyticsos/data-sources/:id

POST   /analyticsos/records/ingest
POST   /analyticsos/records/bulk
POST   /analyticsos/records/query

GET    /analyticsos/metrics
POST   /analyticsos/metrics
GET    /analyticsos/metrics/:id
PUT    /analyticsos/metrics/:id
POST   /analyticsos/metrics/:id/calculate
POST   /analyticsos/query

GET    /analyticsos/kpis
POST   /analyticsos/kpis
GET    /analyticsos/kpis/:id
POST   /analyticsos/kpis/:id/calculate

GET    /analyticsos/dashboards
POST   /analyticsos/dashboards
GET    /analyticsos/dashboards/:id
PUT    /analyticsos/dashboards/:id
POST   /analyticsos/dashboards/:id/render

GET    /analyticsos/reports
POST   /analyticsos/reports
GET    /analyticsos/reports/:id
POST   /analyticsos/reports/:id/generate

GET    /analyticsos/alerts/rules
POST   /analyticsos/alerts/rules
POST   /analyticsos/alerts/evaluate
GET    /analyticsos/alerts/incidents
PATCH  /analyticsos/alerts/incidents/:id

POST   /analyticsos/exports
GET    /analyticsos/exports/:id

GET    /analyticsos/events
GET    /analyticsos/audit-logs

Production upgrade path

For production, replace the JSON file store with:

PostgreSQL for relational storage
Redis for cache
Queue system for ingestion jobs
Object storage for exported reports
Warehouse/OLAP engine for heavy analytics
NestJS/Fastify for API framework
Prisma/Drizzle for database access
SecurityOS for full RBAC
AutomationOS for alert/report delivery

The included database/schema.sql gives a PostgreSQL starting point.

Planning Alignment

• Official package: @appneurox/analyticsos
• Manifest: manifest.json
• Domain API namespace: /v1/analytics
• Modes: standalone and PlatformOS integrated
• Related systems: PlatformOS, DataOS

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