# NexGate Platfom (Entry)

# Social Commerce Platform (Intro)

Nexgate is a unified social commerce platform that combines eCommerce, event management, and social networking into a single ecosystem. Built for the East African market, Nexgate enables users to buy, sell, connect, and experience — all in one place.

---

## The Concept

Nexgate reimagines how commerce happens online. Instead of separating shopping, events, and social media into different apps, Nexgate brings them together.

**User creates** → Product or Event → **Posts to Social** → Followers see in feed → **Purchase or Book**

A product isn't just listed in a shop — it's shared, liked, and commented on. An event isn't just a ticket page — it's a post that spreads organically through your network.

---

## Platform Architecture

Nexgate follows a microservices architecture with nine independent services communicating via RabbitMQ message broker and backed by PostgreSQL databases.

### Core Services

1. **Authentication** — User registration, login, JWT tokens, OAuth, device management
2. **User Profile** — Profiles, followers/following, privacy settings, trust scores
3. **File Manager** — Media uploads, image processing, BlurHash, video transcoding via FFmpeg
4. **Payment** — Payment methods, M-Pesa/Selcom/Tembo Plus integration, escrow, transactions
5. **Direct Message** — Real-time private messaging, conversations, media sharing

### Business Services

6. **E-Commerce** — Shops, products, orders, cart, checkout, reviews, seller verification
7. **E-Events** — Event creation, ticketing, RSA-signed tickets, check-ins, organizer ratings
8. **E-Social** — Posts, feeds, likes, comments, reposts, polls, mentions, hashtags

### External Service

9. **Notification** — Push notifications, in-app alerts, email, SMS (async via RabbitMQ)

---

## Architecture Diagram

[![nexgate_arc_diagram.png](https://doc-hub.qbitspark.com/uploads/images/gallery/2025-12/scaled-1680-/nexgate-arc-diagram.png)](https://doc-hub.qbitspark.com/uploads/images/gallery/2025-12/nexgate-arc-diagram.png)

---

## Service Relationships

<table id="bkmrk-service-role-connect"><thead><tr><th>Service</th><th>Role</th><th>Connects To</th></tr></thead><tbody><tr><td>**Authentication**</td><td>Identity, tokens, sessions</td><td>Redis, PostgreSQL Core, RabbitMQ</td></tr><tr><td>**User Profile**</td><td>Profiles, follows, trust scores</td><td>PostgreSQL Core, RabbitMQ</td></tr><tr><td>**File Manager**</td><td>Media uploads, processing</td><td>FFmpeg, MinIO, PostgreSQL Core</td></tr><tr><td>**Payment**</td><td>Transactions, escrow</td><td>M-Pesa, Selcom, Tembo Plus, PostgreSQL Core, RabbitMQ</td></tr><tr><td>**Direct Message**</td><td>Private conversations</td><td>PostgreSQL Core, RabbitMQ</td></tr><tr><td>**E-Commerce**</td><td>Shops, products, orders</td><td>E-Social (embed products in posts), PostgreSQL Core, RabbitMQ</td></tr><tr><td>**E-Events**</td><td>Events, tickets, check-ins</td><td>E-Social (embed events in posts), PostgreSQL Core, RabbitMQ</td></tr><tr><td>**E-Social**</td><td>Posts, feeds, interactions</td><td>E-Commerce, E-Events (receives embeds), PostgreSQL Core, RabbitMQ</td></tr><tr><td>**Notification**</td><td>Push, email, SMS</td><td>RabbitMQ (consumes events), PostgreSQL Notif</td></tr></tbody></table>

---

## Data Flow Summary

<table id="bkmrk-flow-path-user-creat"><thead><tr><th>Flow</th><th>Path</th></tr></thead><tbody><tr><td>**User creates product**</td><td>E-Commerce → Post to E-Social → Followers see in feed</td></tr><tr><td>**User creates event**</td><td>E-Events → Post to E-Social → Followers see in feed</td></tr><tr><td>**User uploads media**</td><td>File Manager → FFmpeg (if video) → MinIO → BlurHash generated</td></tr><tr><td>**User makes payment**</td><td>Payment → External Provider (M-Pesa/Selcom/Tembo) → Callback → Update order</td></tr><tr><td>**Any action triggers notification**</td><td>Service → RabbitMQ → Notification Service → Push/Email/SMS</td></tr></tbody></table>

---

## Infrastructure Components

<table id="bkmrk-component-purpose-po"><thead><tr><th>Component</th><th>Purpose</th></tr></thead><tbody><tr><td>**PostgreSQL (Core)**</td><td>Shared DB for Auth, User, File, Payment, DM, E-Commerce, E-Events, E-Social</td></tr><tr><td>**PostgreSQL (Notif)**</td><td>Separate DB for Notification service</td></tr><tr><td>**Redis**</td><td>Session storage, caching, rate limiting</td></tr><tr><td>**RabbitMQ**</td><td>Async messaging, triggers notifications</td></tr><tr><td>**MinIO**</td><td>S3-compatible object storage for all media</td></tr><tr><td>**FFmpeg**</td><td>Video transcoding, thumbnails, compression</td></tr></tbody></table>

---

## Tech Stack

<table id="bkmrk-layer-technology-bac"><thead><tr><th>Layer</th><th>Technology</th></tr></thead><tbody><tr><td>**Backend**</td><td>Java 21, Spring Boot 3.x</td></tr><tr><td>**Database**</td><td>PostgreSQL (Core + Notification)</td></tr><tr><td>**Cache**</td><td>Redis</td></tr><tr><td>**Messaging**</td><td>RabbitMQ</td></tr><tr><td>**Storage**</td><td>MinIO (S3-compatible)</td></tr><tr><td>**Media Processing**</td><td>FFmpeg</td></tr><tr><td>**Payments**</td><td>M-Pesa, Selcom, Tembo Plus</td></tr><tr><td>**Security**</td><td>JWT, RSA signatures, device fingerprinting</td></tr></tbody></table>

# Services Requrements

## Core Services

### 1. Authentication Service

Handles all identity and access management for the platform.

**What it does:**

- User registration (email, phone, social OAuth)
- Login/logout with JWT token generation
- Access token &amp; refresh token management
- Password reset and email verification
- Device management and tracking
- Session management via Redis
- Multi-factor authentication support

**Key concepts:**

- Tokens are short-lived (access) + long-lived (refresh)
- Each device is fingerprinted and tracked
- Failed login attempts trigger rate limiting
- OAuth supports Google, Apple, Facebook

---

### 2. User Profile Service

Manages user identity, relationships, and platform reputation.

**What it does:**

- Profile creation and editing (bio, avatar, cover photo)
- Username and display name management
- Follow/unfollow functionality
- Followers and following lists
- Block and mute users
- Privacy settings (public/private account)
- Trust score calculation for sellers and organizers
- Account verification status

**Key concepts:**

- Private accounts require follow approval
- Trust scores build over time based on transactions and feedback
- Blocking hides all content bidirectionally
- Profiles link to shops (E-Commerce) and organizer pages (E-Events)

---

### 3. File Manager Service

Central media handling for the entire platform.

**What it does:**

- Image uploads with compression and resizing
- Video uploads with FFmpeg transcoding
- BlurHash generation for image placeholders
- Multiple format support (JPEG, PNG, WebP, MP4, MOV)
- Thumbnail generation for videos
- File validation (size limits, type checking)
- CDN-ready URL generation via MinIO
- Parallel upload processing for multiple files

**Key concepts:**

- All media goes through this service regardless of source (posts, products, events, messages)
- Videos are transcoded to web-optimized formats
- BlurHash provides instant low-res preview while full image loads
- Files are stored in MinIO with organized bucket structure

---

### 4. Payment Service

Handles all money movement on the platform.

**What it does:**

- Payment method management (add/remove cards, mobile money)
- M-Pesa, Selcom, Tembo Plus integration
- Payment initiation and callback processing
- Escrow system for marketplace transactions
- Escrow release upon delivery confirmation or event completion
- Refund processing
- Transaction history and receipts
- Payout to sellers and organizers

**Key concepts:**

- Escrow protects buyers — money is held until satisfaction
- Event payments release after event completes with good feedback
- Product payments release after delivery confirmation
- All transactions are logged for audit and dispute resolution

---

### 5. Direct Message Service

Private real-time communication between users.

**What it does:**

- One-on-one conversations
- Group conversations
- Text messages
- Media sharing (images, videos via File Manager)
- Read receipts and typing indicators
- Message reactions
- Conversation muting
- Message search

**Key concepts:**

- Messages are stored persistently
- Blocked users cannot send messages
- Media in DMs goes through File Manager
- Supports future WebSocket integration for real-time delivery

---

## Business Services

### 6. E-Commerce Service

Full marketplace functionality for buying and selling products.

**What it does:**

- Shop creation and management
- Product listing with variants (size, color, etc.)
- Inventory tracking
- Shopping cart management
- Multiple checkout options (see below)
- Order management and status tracking
- Delivery address management
- Product reviews and ratings
- Seller verification and trust badges
- Wishlist/saved items

**Purchase Options:**

<table id="bkmrk-type-description-ind"><thead><tr><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>**Individual**</td><td>Buy single item, standard checkout</td></tr><tr><td>**Quantity-based**</td><td>Buy multiple units, bulk pricing available</td></tr><tr><td>**Group Buy**</td><td>Multiple buyers join to unlock discount, minimum participants required</td></tr><tr><td>**Buy Together**</td><td>Friends pool money for shared purchase (gifts, shared items)</td></tr><tr><td>**Installment**</td><td>Pay in scheduled parts, product released after full payment or based on seller terms</td></tr></tbody></table>

**Key concepts:**

- Group buy has deadline and minimum participant threshold
- Installment plans are configured per product by seller
- Buy together splits payment among participants
- All payments go through escrow until delivery confirmed
- Sellers build trust score through successful transactions

---

### 7. E-Events Service

Complete event management from creation to check-in.

**What it does:**

- Event creation with draft system (step-by-step)
- Ticket type management (free, paid, VIP, early bird)
- Ticket quantity and availability tracking
- RSA-signed secure tickets (QR code)
- Check-in system with multiple methods
- Attendee management
- Event analytics (views, sales, check-ins)
- Organizer ratings and reviews
- Refund handling for cancelled events

**Event Types:**

<table id="bkmrk-type-description-in-"><thead><tr><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>**In-Person**</td><td>Physical location, requires venue details and check-in</td></tr><tr><td>**Online**</td><td>Virtual event, streaming link provided to ticket holders</td></tr><tr><td>**One-Time**</td><td>Single date/time event</td></tr><tr><td>**Multi-Day**</td><td>Spans multiple days (festivals, conferences), each day can have separate check-in</td></tr></tbody></table>

**Check-in System:**

<table id="bkmrk-method-use-case-mobi"><thead><tr><th>Method</th><th>Use Case</th></tr></thead><tbody><tr><td>**Mobile App Scan**</td><td>Organizer uses Nexgate app to scan attendee QR</td></tr><tr><td>**Ticket Scanner Machine**</td><td>Hardware scanner integration via API</td></tr><tr><td>**Manual Entry**</td><td>Enter ticket code manually for backup</td></tr><tr><td>**Self Check-in Kiosk**</td><td>Attendee scans own ticket at kiosk</td></tr></tbody></table>

**Key concepts:**

- One draft at a time per user (prevents abandoned drafts piling up)
- Tickets are RSA-signed to prevent forgery
- Multi-day events track check-in per day
- Online events auto-deliver streaming link after purchase
- Escrow holds payment until event completes successfully
- Bad events (cancellation, poor feedback) affect organizer trust score

---

### 8. E-Social Service

The social layer that connects everything together.

**What it does:**

- Post creation (text, images, videos)
- Product embeds in posts (from E-Commerce)
- Event embeds in posts (from E-Events)
- Feed generation (following, trending, discover)
- Like, comment, repost interactions
- Bookmarks/save posts
- Polls with voting
- Mentions: @users, $shops
- Hashtags (#topics)
- Collaborative posts (multiple authors)
- Scheduled posting
- Post visibility controls (public, followers only)

**Post Types:**

<table id="bkmrk-type-description-sta"><thead><tr><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>**Standard**</td><td>Text + optional media</td></tr><tr><td>**Product Post**</td><td>Embedded product card, click to buy</td></tr><tr><td>**Event Post**</td><td>Embedded event card, click to book</td></tr><tr><td>**Poll**</td><td>Question with voting options, timed or open</td></tr><tr><td>**Collaborative**</td><td>Multiple users co-author, shared credit</td></tr><tr><td>**Repost**</td><td>Share another post with optional comment</td></tr></tbody></table>

**Key concepts:**

- E-Social is the hub — products and events flow through it
- Feed algorithm considers follows, engagement, recency
- Product/event posts drive organic discovery and sales
- Polls can be standalone or attached to products (customer feedback)
- Collaborative posts useful for brand partnerships, co-selling

---

## External Service

### 9. Notification Service

Async notification delivery across all channels.

**What it does:**

- Push notifications (mobile/web)
- In-app notification center
- Email notifications
- SMS notifications
- Notification preferences management
- Read/unread status tracking
- Notification grouping (batch similar notifications)
- Scheduled notifications
- Delivery status tracking

**How it works:**

```
Any Service → Event → RabbitMQ → Notification Service → Deliver

```

Notification service is fully decoupled. It only listens to RabbitMQ events and decides how to notify based on user preferences.

**Notification Triggers:**

<table id="bkmrk-source-events-auth-w"><thead><tr><th>Source</th><th>Events</th></tr></thead><tbody><tr><td>**Auth**</td><td>Welcome, password reset, new device login, suspicious activity</td></tr><tr><td>**User Profile**</td><td>New follower, follow request (private account), mention</td></tr><tr><td>**Direct Message**</td><td>New message, message reaction</td></tr><tr><td>**E-Commerce**</td><td>Order placed, order shipped, order delivered, payment received (seller), review received, group buy progress, installment reminder</td></tr><tr><td>**E-Events**</td><td>Ticket purchased, event reminder, event cancelled, check-in confirmation, event starting soon</td></tr><tr><td>**E-Social**</td><td>Like, comment, repost, mention (@user), shop mention ($shop), poll ended, collaborative post invite</td></tr><tr><td>**Payment**</td><td>Payment successful, payment failed, escrow released, refund processed, payout sent</td></tr></tbody></table>

**User Preferences:**

<table id="bkmrk-setting-options-push"><thead><tr><th>Setting</th><th>Options</th></tr></thead><tbody><tr><td>**Push**</td><td>All, important only, none</td></tr><tr><td>**Email**</td><td>All, digest (daily/weekly), none</td></tr><tr><td>**SMS**</td><td>Critical only (payments, security), none</td></tr><tr><td>**Quiet hours**</td><td>Disable notifications during set hours</td></tr><tr><td>**Per-type toggle**</td><td>Enable/disable specific notification types</td></tr></tbody></table>

**Key concepts:**

- User controls what they receive and how
- Critical notifications (security, payments) bypass quiet hours
- Similar notifications are grouped (e.g., "5 people liked your post")
- Failed deliveries are retried with exponential backoff
- Separate database to not impact core service performance

---