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


Opens GUI at http://localhost:5555 to browse your data.

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! 🚀

---

Developed by ETK Technologies © 2024-2025
Last Updated: November 9, 2025
Version: 1.0.0