Netafrooz — Technical Documentation

Project Overview

Netafrooz Platform

A full-stack reseller management platform enabling users to activate, manage, and renew digital services. Includes wallet-based payments via ZarinPal, a complete ticketing system, admin panel, and real-time metrics.

Monorepo3 MicroservicesPostgreSQL + RedisDocker ComposeOpenAPI 3.0

System Architecture

Three services orchestrated via Docker Compose behind an Nginx reverse proxy.

API Server

Business logic, auth, payments

Bun + Hono

Prisma ORM

TypeScript

Port :3111

Public App

Customer-facing web application

Nuxt 4 (Vue 3)

Three.js / GSAP

UnoCSS

Port :3000

Admin Dashboard

Management panel for administrators

Vue 3 + Vite

ApexCharts

UnoCSS + Pinia

Port :5173

PostgreSQL 16

Primary relational database. 19 tables via Prisma schema. Alpine image with persistent volume.

Redis 7

Caching and session store. AOF persistence enabled. Alpine image with persistent volume.

Technology Stack

Core technologies and tools used across the platform.

Layer	Technology	Purpose
Runtime	Bun	Fast JS/TS runtime for API and builds
API Framework	Hono	Lightweight, edge-ready HTTP framework
ORM	Prisma (with pg adapter)	Type-safe database access and migrations
Frontend (Public)	Nuxt 4 / Vue 3	SSR/SSG public-facing application
Frontend (Admin)	Vue 3 + Vite	SPA admin dashboard
CSS	UnoCSS	Utility-first CSS for both frontends
State Management	Pinia	Vue state management
Database	PostgreSQL 16	Primary data store
Cache	Redis 7	Session and cache layer
Validation	Zod	Runtime schema validation
Payments	ZarinPal Gateway	Wallet top-up and payment processing
Containerization	Docker Compose	Multi-service orchestration
Reverse Proxy	Nginx	HTTPS termination and routing
Testing	Bun test + Vitest + Playwright	Unit, integration, and E2E testing
Linting	ESLint + OxLint + OxFmt	Code quality and formatting

API Server

RESTful API built with Hono on Bun, using Prisma for database access.

Project Structure

server/src/
├── index.ts
├── config/
│   └── env.config.ts
├── lib/
│   ├── prisma.ts
│   └── redis.ts
├── middlewares/
│   ├── auth.middleware.ts
│   └── prisma.middleware.ts
├── api/
│   ├── auth/
│   ├── users/
│   ├── admin/
│   ├── services/
│   ├── wallets/
│   ├── tickets/
│   ├── notifications/
│   ├── plans/
│   ├── categories/
│   ├── features/
│   ├── invoices/
│   ├── transactions/
│   ├── business-profiles/
│   ├── bank-accounts/
│   ├── faqs/
│   ├── footer/
│   └── metrics/
├── modules/
│   └── referral/
├── cron/
│   └── renewal.cron.ts
└── utils/
    ├── token.utils.ts
    ├── random.utils.ts
    └── zarinpal.utils.ts

Key Features

User registration with phone OTP verification
Admin authentication with JWT + cookie sessions
Service activation with full lifecycle management
ZarinPal wallet top-up with callback handling
Service cancellation with automatic refund logic
Service revocation for near-ending services
Ticketing system (user + admin sides)
Notification engine (15 notification types)
Referral traffic source tracking with rate limiting
Cron job for automatic service renewals
Admin metrics and platform analytics

Public Application

Customer-facing Nuxt 4 application with 3D elements and animations.

Framework

Nuxt 4 with Vue 3 Composition API and script setup

3D & Animation

Three.js for 3D graphics, GSAP and Motion-V for smooth animations

UI Libraries

Lucide icons, OverlayScrollbars, VueUse composables

Key Pages

Landing / HomeProduct CatalogService DashboardWallet & PaymentsTicketsNotificationsHelp / FAQUser Profile

Admin Dashboard

Vue 3 SPA for platform administration.

Tech Details

Vue 3 with Composition API
Vite 8 build tool with devtools
ApexCharts for data visualization
Pinia for state management
Vue Sonner for toast notifications
FormKit Auto-Animate for list transitions

Admin Capabilities

User management (CRUD + KYC review + status)
Service lifecycle management
Ticket management and responses
Notification broadcast to users
Platform-wide metrics dashboard
Deposit statistics and financial overview
FAQ and footer content management

Code Quality

OxLintESLintOxFmtVitest (Unit)Playwright (E2E)

Database Schema

19 models managed via Prisma with PostgreSQL. Full relational design with indexes.

Core Entities

User

Profile, KYC docs, status (PENDING/ACTIVE/SUSPENDED/REJECTED)

Admin

Role-based (SUPPORT/ADMIN/OWNER), bcrypt password

BusinessProfile

Company info, economic code, registration

BankAccount

Card number, IBAN, approval status

Commerce & Services

ProductCategory

Service categories with active/inactive toggle

ProductPlan

Monthly + yearly pricing, features list

Service

7-state lifecycle, expiry tracking, credentials

Invoice

Renewal invoices with due dates and status

Financial

Wallet

BigInt balance per user, cascade delete

WalletTransaction

Deposit/Withdraw/Refund/Cancellation/Revocation

ServiceTransaction

Activation, renewal, cancellation, revocation

Support & Communication

Ticket + TicketMessage

Department-categorized, threaded messaging

Notification

15 types, read tracking, related entity links

Faq + Footer

CMS-managed content, public reads, admin writes

ReferralSource

Traffic attribution with daily aggregation

API Endpoints Overview

Full OpenAPI 3.0 spec available at server/openapi/openapi.yaml. 21 tag groups.

Group	Endpoints	Auth
System	/health	Public
Auth	login, register, OTP, logout, me	Mixed
Users	CRUD, KYC, status	Admin
Admins	CRUD, status, password	Admin
Services	activate, list, cancel, revoke, credentials	User
Wallet	balance, top-up, callback, transactions	User
Tickets	create, list, view, reply	Mixed
Notifications	list, read, delete, admin broadcast	Mixed
Products	categories, plans, features	Mixed
Metrics	admin platform metrics, user personal metrics	Mixed
Invoices	list, counts, details	User
Transactions	service transaction history	User
Bank Accounts	CRUD, status (admin) / user-facing	Mixed
Business Profiles	CRUD (admin) / user-facing	Mixed
FAQs & Footer	CMS content management	Mixed
Referrals	traffic source tracking	Public

Service Lifecycle

7-state machine governing the full lifecycle of each activated service.

Pending Review

Initial state

Preparing

Setup in progress

Active

Fully operational

Near Ending

Expiry approaching

Expired

Service ended

CANCEL

Order Cancelled

20% fee in PREPARING

REVOKE

Revoked

From NEAR_ENDING only

Deployment Architecture

Docker Compose orchestration with Nginx reverse proxy for HTTPS.

Docker Services

# compose.yml — 7 services

db          postgres:16-alpine     # Persistent volume
redis       redis:7-alpine         # AOF persistence
migrate     one-shot               # Prisma migrate deploy
seed        one-shot               # Idempotent seed
api         Bun + Hono             # Depends on db, redis
app         Nuxt 4                 # Depends on api
dash        Vite SPA + Nginx       # Depends on api

# All ports bound to 127.0.0.1 only
# Host Nginx terminates HTTPS

Startup Order

db + redis→migrate→seed→api→app + dash

Security

Authentication, authorization, and security measures across the platform.

Authentication

User: Phone + OTP verification, JWT in ntafu_token cookie
Admin: Email + password (bcrypt), JWT in ntafa_token cookie
Bearer token support for API access
Separate cookie namespaces per role

Infrastructure

All ports bound to 127.0.0.1 only
Nginx HTTPS termination with subdomain routing
Health checks on all services
Redis rate limiting for referral tracking
Referral spam domain filtering
Environment variables for all secrets

Environments

Production and local development configurations.

PRODUCTION

Public Sitehttps://ntaf.xerobase.xyz

APIhttps://api.ntaf.xerobase.xyz

Dashboardhttps://dash.ntaf.xerobase.xyz

LOCAL DEV

Public Sitehttp://localhost:3000

APIhttp://localhost:3111/api

Dashboardhttp://localhost:5173

Useful Data

Quick links, test credentials, and sample accounts.

Links

Temp OTPntaf.xerobase.xyz/temp/otp/[phone_number]

Dashboarddash.xerobase.xyz

Test Credentials

navid@gmail.com12341234

iamshcc@gmail.com11110000

User Account

Test phone number for OTP flow:

09111001010