DatomniX Quick Start Guide

Get your multi-tenant attribution platform running in minutes!

---

✅ What You're Getting

A complete Multi-Tenant Attribution & Analytics SaaS Platform with:

✅ NestJS API with JWT authentication and RBAC
✅ Next.js Dashboard with beautiful dark mode UI
✅ PostgreSQL with multi-tenant schema
✅ Redis Streams for real-time event processing (30x faster)
✅ 5 Attribution Models (last-click, first-click, linear, time-decay, position-based)
✅ Platform Integrations (Meta CAPI, TikTok, GA4, Shopify, WooCommerce)
✅ Complete RBAC (Super Admin, Owner, Admin, Member)
✅ Tracking Pixel ready to deploy
✅ REST API with Swagger documentation
✅ Docker Compose for easy local setup

---

🚀 Quick Start (3 Steps)

Prerequisites

Node.js 18+ and npm

PostgreSQL 14+

Redis 6+

Git

Step 1: Clone & Install

# Clone the repository
git clone https://github.com/etk-technologies/datomnix.git
cd datomnix

# Install dependencies
npm install

Step 2: Setup Environment

# Copy environment template
cp .env.example .env

# Edit .env with your configuration (or use defaults for dev)

Minimal .env configuration:

# Database
DATABASE_URL="postgresql://datomnix:datomnix@127.0.0.1:5432/datomnix?schema=public"

# Redis
REDIS_HOST="localhost"
REDIS_PORT=6379

# App Config
PORT=3001
NODE_ENV="development"
FRONTEND_URL="http://localhost:3000"
JWT_SECRET="your-super-secret-jwt-key-change-in-production-min-32-chars"

Step 3: Start Everything

# Start Docker services (PostgreSQL + Redis)
docker-compose up -d

# Generate Prisma client
npm run db:generate

# Run database migrations
npm run db:migrate

# Seed the database (creates test accounts)
npm run db:seed

# Start development servers (API + Web)
npm run dev

---

🎉 You're Ready!

Open your browser and visit:

Dashboard: http://localhost:3000

API: http://localhost:3001

API Documentation: http://localhost:3001/docs

Swagger UI: http://localhost:3001/api/docs

---

🔐 Test Accounts

After seeding, you can log in with these accounts:

Super Admin (ETK Technologies)

Email: superadmin@etk.com

Password: ETK@SuperAdmin2024

Role: Full platform access, can manage all workspaces

Client (Rocky - Demo Workspace)

Email: owner@demo.example.com

Password: see .seed-credentials.json, generated by npm run db:seed

Role: Workspace Owner

---

📊 What's Included

1. Multi-Tenant Workspaces

Create unlimited workspaces

Each workspace isolated from others

Invite team members with different roles

2. Brand Management

Multiple brands per workspace

Each brand has its own tracking pixel

Independent integrations per brand

3. Event Tracking

Client-side: JavaScript tracking pixel

Server-side: REST API for events

Webhooks: WooCommerce, Shopify support

Queue Processing: 3 parallel consumers (30x faster)

4. Attribution Models

Last-Click: 100% credit to final touch

First-Click: 100% credit to first touch

Linear: Equal credit across all touches

Time-Decay: More weight to recent touches

Position-Based: U-shaped (40/40/20)

5. Platform Integrations

Meta Conversions API (CAPI)

TikTok Events API

Google Analytics 4

Custom webhooks

6. Beautiful Dashboard

Real-time analytics

Revenue tracking

Conversion funnels

Traffic source analysis

Event timeline

Dark mode support

---

🎯 First Steps After Login

1. Create Your First Brand

1. Log in to http://localhost:3000
2. Go to Dashboard → Settings
3. Click "+ Add Brand"
4. Fill in:
- Name: "My Store"
- Domain: "mystore.com"
- Timezone, Currency, Vertical
5. Click "Create Brand"
6. Your pixel keys are generated automatically!

2. Install the Tracking Pixel

<!-- Add this to your website's <head> -->
<script src="http://localhost:3001/pixel.js"></script>
<script>
  DatomniX.init('YOUR_PIXEL_API_KEY'); // From brand settings
  DatomniX.track('page_view');
</script>

3. Send a Test Event

// Track a purchase
DatomniX.track('purchase', {
  order_id: 'test-order-123',
  order_total: 99.99,
  currency: 'USD',
  email: 'customer@example.com'
});

4. Connect Integrations

1. Go to Dashboard → Integrations
2. Click on platform (Meta, TikTok, GA4)
3. Enter your credentials/access tokens
4. Save configuration
5. Events will be forwarded automatically!

5. View Your Data

Overview: Dashboard with KPIs

Events: Real-time event stream

Attributions: See which sources drive revenue

Sources: Traffic channel breakdown

---

🛠️ Useful Commands

Development

npm run dev              # Start API + Web
npm run dev:api          # Start only API
npm run dev:web          # Start only Web

Database

npm run db:generate      # Generate Prisma client
npm run db:migrate       # Run migrations
npm run db:seed          # Seed database
npm run db:studio        # Open Prisma Studio (GUI)
npm run db:reset         # Reset database (⚠️ deletes all data)

Docker

docker-compose up -d     # Start services
docker-compose down      # Stop services
docker-compose logs -f   # View logs

Production

npm run build            # Build all apps
npm run start            # Start production

---

🔍 Verify Everything Works

1. Check API Health

curl http://localhost:3001/health

Expected response:

{
  "status": "ok",
  "timestamp": "2025-11-09T...",
  "database": "connected"
}

2. Check Database

npm run db:studio

3. Check Redis

docker exec -it datomnix-redis redis-cli
> XINFO STREAM datomnix:events

4. Test Login

1. Visit http://localhost:3000
2. Click "Sign In"
3. Use test credentials
4. Should see dashboard

5. Test API Endpoints

Visit http://localhost:3001/api/docs (Swagger UI) and try:

GET /api/v1/health - Health check

POST /api/auth/login - Login

GET /api/v1/workspaces - Get workspaces (requires auth)

---

🐛 Troubleshooting

"Database connection failed"

Problem: PostgreSQL not running

Solution:

docker-compose up -d postgres
# Wait 5 seconds for startup
npm run db:migrate

"Port already in use"

Problem: Port 3000 or 3001 is occupied

Solution:

# Windows
netstat -ano | findstr :3000
# Kill process or change PORT in .env

# Mac/Linux
lsof -i :3000

"Prisma client not generated"

Problem: Missing Prisma client

Solution:

npm run db:generate

"Redis connection error"

Problem: Redis not running

Solution:

docker-compose up -d redis

"Frontend 404 error"

Problem: Empty app directory conflict

Solution:

# Remove empty app directory
rm -rf apps/web/app
# Restart dev server
npm run dev

"Events not appearing"

Checklist:
1. ✅ Redis is running: docker ps
2. ✅ Event sent to correct brand API key
3. ✅ Check API logs: docker logs -f datomnix-api
4. ✅ Check queue: curl -H "Authorization: Bearer $TOKEN" http://localhost:3001/api/v1/system/queue/stats

---

📖 Next Steps

Learn the Platform

1. Read Documentation
- Architecture Guide - System design
- API Reference - All endpoints
- Onboarding Guide - Client walkthrough
- Attribution Models - Model comparison

2. Explore the Dashboard
- Overview page with KPIs
- Events page (real-time stream)
- Attributions page (conversion details)
- Sources page (traffic analysis)
- Integrations (connect platforms)
- Settings (manage team, brands)

3. Test Integrations
- Connect Meta CAPI
- Set up TikTok Events API
- Configure Google Analytics 4
- Add custom webhooks

Deploy to Production

See Deployment Guide for:

Railway deployment (API + Database + Redis)

Vercel deployment (Web dashboard)

Environment configuration

DNS and SSL setup

Monitoring and backups

Customize

Add custom attribution models

Extend integration framework

Create custom reports

Build mobile app

White-label the UI

---

💡 Pro Tips

1. Use Prisma Studio for easy database inspection: npm run db:studio
2. Check Queue Stats to monitor performance: http://localhost:3001/api/v1/redis/stats
3. Swagger UI is your friend for testing: http://localhost:3001/api/docs
4. Enable Dark Mode in dashboard for better viewing
5. Use Test Accounts provided for quick testing
6. Check Health Endpoint regularly: http://localhost:3001/health

---

📚 Project Structure

DatomniX/
├── apps/
│   ├── api/                 # NestJS backend
│   │   ├── src/
│   │   │   ├── auth/        # Authentication
│   │   │   ├── workspaces/  # Multi-tenant workspaces
│   │   │   ├── brands/      # Brand management
│   │   │   ├── ingestion/   # Event ingestion
│   │   │   ├── attribution/ # Attribution engine (30x faster!)
│   │   │   ├── reporting/   # Analytics
│   │   │   ├── integrations/# Platform connectors
│   │   │   └── ...
│   │   └── prisma/
│   │       └── schema.prisma # Database schema
│   └── web/                 # Next.js dashboard
│       └── src/
│           ├── app/         # App Router pages
│           ├── components/  # UI components
│           └── lib/         # API client
├── packages/
│   ├── types/               # Shared TypeScript types
│   ├── config/              # Shared constants
│   └── pixel/               # Tracking pixel SDK
├── docs/                    # Documentation
├── prisma/                  # Database migrations
├── docker-compose.yml       # Local development
└── package.json             # Workspace root

---

🆘 Getting Help

Documentation

API Docs: http://localhost:3001/docs

Swagger UI: http://localhost:3001/api/docs

Architecture: ARCHITECTURE.md

API Reference: API_REFERENCE.md

Support

Email: support@etk.com

Issues: GitHub Issues

Website: https://etk.com

---

✨ Summary

You now have a fully functional attribution platform that:

1. ✅ Tracks events via pixel or API
2. ✅ Processes events in real-time (30x faster!)
3. ✅ Attributes conversions with 5 models
4. ✅ Forwards events to Meta, TikTok, GA4
5. ✅ Displays analytics in beautiful dashboard
6. ✅ Supports unlimited workspaces & brands
7. ✅ Includes complete RBAC system
8. ✅ Ready for production deployment

The foundation is solid, extensible, and production-ready!

Happy tracking! 🚀

---

📚 DatomniX Documentation

DatomniX Quick Start Guide

✅ What You're Getting

🚀 Quick Start (3 Steps)

Prerequisites

Step 1: Clone & Install

Step 2: Setup Environment

Step 3: Start Everything

🎉 You're Ready!

🔐 Test Accounts

Super Admin (ETK Technologies)

Client (Rocky - Demo Workspace)

📊 What's Included

1. Multi-Tenant Workspaces

2. Brand Management

3. Event Tracking

4. Attribution Models

5. Platform Integrations

6. Beautiful Dashboard

🎯 First Steps After Login

1. Create Your First Brand

2. Install the Tracking Pixel

3. Send a Test Event

4. Connect Integrations

5. View Your Data

🛠️ Useful Commands

Development

Database

Docker

Production

🔍 Verify Everything Works

1. Check API Health

2. Check Database

3. Check Redis

4. Test Login

5. Test API Endpoints

🐛 Troubleshooting

"Database connection failed"

"Port already in use"

"Prisma client not generated"

"Redis connection error"

"Frontend 404 error"

"Events not appearing"

📖 Next Steps

Learn the Platform

Deploy to Production

Customize

💡 Pro Tips

📚 Project Structure

🆘 Getting Help

Documentation

Support

✨ Summary