Eneza API Architecture

The Eneza API is a Node.js + Express + Prisma application serving as the core backend for the Eneza advertising platform.

Technology Stack

Component	Technology
Runtime	Node.js 20
Framework	Express.js
ORM	Prisma (PostgreSQL)
Auth	JWT + bcrypt
File Upload	express-fileupload
Message Broker	Google Pub/Sub / RabbitMQ
Storage	Cloudflare R2
Payments	Stripe
Documentation	Swagger UI

Project Structure

src/
├── app.ts                    # Express app setup & routes
├── db/
│   └── prisma.ts            # Prisma client instance
├── controllers/             # Request handlers (37 controllers)
├── routes/                  # Route definitions (39 route files)
│   └── admin/               # Admin-specific routes (18 files)
├── services/                # Business logic (65+ services)
├── middleware/              # Auth, geo, rate-limiting (14 files)
├── utils/                   # Helpers & utilities
├── swagger/                 # API documentation
└── cron/                    # Background jobs

Core Features

Authentication

• User Auth: Phone number + OTP verification
• Advertiser Auth: Email/password + email verification
• Admin Auth: Email/password + role-based access
• JWT Tokens: Access tokens with configurable expiry

Message Broker Abstraction

The API uses a unified messaging interface supporting multiple backends:

// Publish a message (works with Pub/Sub, RabbitMQ, or InMemory)
messagingService.publish(TOPICS.VIDEO_PROCESSING, {
  ad_id: adId,
  video_url: videoUrl,
  type: 'process_ad_video'
});

Topics:

• video-processing - Trigger video processing
• video-processed - Video processing complete
• screenshot-verify - Trigger screenshot verification
• screenshot-processed - Verification results
• push-notification - Send push notifications
• whatsapp-message - Send WhatsApp messages
• email-verification - Send verification emails
• invoice-email - Send invoice emails

Rate Limiting

// OTP rate limiting with exponential backoff
const OTP_CONFIG = {
  maxAttempts: 5,
  lockoutMinutes: 15,
  cooldownWindow: 60 // seconds between OTPs
};

Key Endpoints

User Endpoints (/users, /auth)

• POST /auth/request-otp - Request SMS OTP
• POST /auth/verify-otp - Verify and create session
• GET /users/profile - Get user profile
• PUT /users/profile - Update profile
• GET /users/balance - Get earnings balance

Advertiser Endpoints (/advertisers)

• POST /advertisers/signup - Create account
• POST /advertisers/login - Authenticate
• GET /advertisers/campaigns - List campaigns
• POST /advertisers/campaigns - Create campaign
• GET /advertisers/balance - Account balance

Ad Endpoints (/ads)

• GET /ads - List available ads (for posters)
• GET /ads/:id - Ad details
• POST /ads - Create ad (advertiser only)
• PUT /ads/:id - Update ad
• GET /ads/:id/stats - Campaign statistics

Subscription Endpoints (/subscriptions)

• POST /subscriptions - Subscribe to ad
• GET /subscriptions - User's subscriptions
• GET /subscriptions/:id/video - Get personalized video

Screenshot Endpoints (/screenshots)

• POST /screenshots - Submit proof screenshot
• GET /screenshots - User's screenshot history
• GET /screenshots/:id - Screenshot status

Transaction Endpoints (/transactions)

• GET /transactions - User's transaction history
• POST /transactions/withdraw - Request withdrawal
• GET /transactions/:code - Transaction status

Admin Endpoints (/admin)

All admin routes require authentication + role-based authorization:

• /admin/users - User management
• /admin/advertisers - Advertiser management
• /admin/ads - Ad moderation
• /admin/screenshots - Screenshot review queue
• /admin/finance - Financial operations
• /admin/system - System health & logs

Startup Process

async function startServer() {
  // 1. Seed initial admin user
  await AdminAuthService.seedInitialAdmin();

  // 2. Seed growth engine data (achievements, tiers)
  await seedGrowthEngine();

  // 3. Initialize exchange rates
  await exchangeRateService.initialize();

  // 4. Initialize message broker
  await initMessageBroker();

  // 5. Start local Pub/Sub subscribers (dev only)
  await startLocalSubscribers();

  // 6. Initialize notification queue
  notificationQueue.start();

  // 7. Start processing monitor crons
  startProcessingMonitor();

  // 8. Start Express server
  app.listen(PORT);
}

Environment Variables

# Database
DATABASE_URL=postgresql://...

# Auth
JWT_SECRET=your-secret-key

# Message Broker
MESSAGE_BROKER=pubsub  # pubsub | rabbitmq | inmemory
GCP_PROJECT_ID=eneza-40ab5

# Stripe
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Storage (Cloudflare R2)
R2_ACCOUNT_ID=...
R2_ACCESS_KEY_ID=...
R2_SECRET_ACCESS_KEY=...
R2_BUCKET_NAME=eneza-media

# Firebase (Push Notifications)
FIREBASE_SERVICE_ACCOUNT=...

# External APIs
GEMINI_API_KEY=...  # For AI moderation
IPINFO_TOKEN=...    # For geo verification

API Documentation

Swagger UI is available at /api-docs with interactive documentation for all endpoints.

Quick Links

• Services Reference
• Controllers Reference
• Routes Map
• Database Models
• Middleware
• Billing & Payments