Skip to content

2KRIKA Technical Documentation

Welcome to the comprehensive technical documentation for the 2KRIKA backend service - a marketplace platform connecting service providers with customers.

🚀 Quick Start

New to 2KRIKA? Start here:

  1. Installation - Set up your development environment
  2. Configuration - Configure databases and services
  3. Running the App - Start developing
# Quick setup
git clone https://github.com/OryStack/2-krika-backend.git
cd 2-krika-backend
pnpm install
cp .env.example .env
pnpm dev:migrate
pnpm dev

📚 What is 2KRIKA?

2KRIKA is a marketplace platform built with Clean Architecture principles, enabling:

  • 🛍️ Service Catalog - Browse and purchase services
  • 👤 User Management - Authentication, roles, and KYC verification
  • 📦 Order Management - Complete order lifecycle with state machines
  • 💳 Payment Processing - Integrated payment gateway (Paystack)
  • 💰 Account System - Balance management, withdrawals, and refunds
  • 💬 Real-time Chat - WebSocket-based messaging
  • 📧 Notifications - Email and in-app notifications
  • 📁 File Storage - Upload management with cloud-ready abstraction

🏗️ Architecture

2KRIKA follows Clean Architecture with four distinct layers:

┌─────────────────────────────────────────────┐
│              Web Layer (NestJS)             │
│  Controllers, Guards, Filters, WebSockets  │
└─────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────┐
│          Application Layer                  │
│      Use Cases, Validators, DTOs            │
└─────────────────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────┐
│            Domain Layer                     │
│   Entities, Value Objects, Repositories     │
└─────────────────────────────────────────────┘
                      ↑
┌─────────────────────────────────────────────┐
│           Adapters Layer                    │
│  SQL, MongoDB, Redis, Email, Storage        │
└─────────────────────────────────────────────┘

Learn more: Architecture Overview

🛠️ Technology Stack

Backend Framework

  • NestJS - Progressive Node.js framework
  • TypeScript - Type-safe development
  • Express - HTTP server

Databases

  • PostgreSQL (via Sequelize) - Primary relational database
  • MongoDB (via Mongoose) - Chat messages
  • Redis - Caching (stats, permissions, ...)

Key Libraries

  • XState - State machine for order workflow
  • Zod - Schema validation
  • JWT - Authentication tokens
  • Decimal.js - Precise decimal arithmetic
  • Paystack - Payment gateway
  • Nodemailer - Email notifications
  • Socket.IO - WebSocket communication

View complete stack: Technology Stack

📖 Documentation Structure

Getting Started

Learn how to set up and run the application: - Installation - Configuration - Environment Variables - Running the App

Architecture

Understand the system design: - Overview - Clean Architecture - Project Structure - Design Principles - Technology Stack

Core Concepts

Master the fundamental patterns: - Domain Layer - Entities and business logic - Application Layer - Use cases and orchestration - Adapters Layer - External integrations - Web Layer - HTTP and WebSocket APIs - Dependency Injection - IoC container

Domain Modules

Explore business domains: - Users - Authentication, roles, KYC - Services - Catalog, categories, options - Orders - Workflow, states, events - Payments - Gateway integration - Accounts - Balance management - Transactions - Audit trail

Features

Deep dive into functionality: - Authentication - JWT tokens and guards - User Management - CRUD operations - KYC Verification - Identity validation - Service Catalog - Browse and search - Order Workflow - State machines - Payment Processing - Paystack integration - Chat System - Real-time messaging - Notifications - Email system - File Uploads - Storage abstraction

Infrastructure

Configure technical infrastructure: - Database - PostgreSQL, MongoDB setup - Caching - Redis strategies - Storage - File management - Logging - File-based logging - Email - Nodemailer configuration

Development

Best practices for developers: - Coding Standards - TypeScript, ESLint, conventions - Testing - Jest, factories, coverage - Migrations - Database schema changes - Debugging - VS Code, logs, troubleshooting - Contributing - Git workflow, PR process

Deployment

Production deployment guide: - Deployment - Docker, Docker Swarm, best practices

🔑 Key Features

Clean Architecture Benefits

  • Testability - Easy unit and integration testing
  • Maintainability - Clear separation of concerns
  • Flexibility - Easy to swap implementations
  • Scalability - Independent layer scaling

Order Workflow (XState)

State-driven order management: 

pending → paid → in_progress → delivered → completed
        ↓
    cancelled

Payment Integration

  • Paystack gateway abstraction
  • Payment initialization and verification
  • Webhook handling for async updates
  • Transaction tracking

Real-time Features

  • WebSocket chat system
  • Live order status updates
  • Instant notifications

🧪 Testing

Comprehensive test coverage: - Unit Tests - Domain entities and value objects - Integration Tests - Use cases and repositories - Test Factories - Consistent test data generation - Mock Implementations - Isolated testing

# Run all tests
pnpm test

# Run with coverage
pnpm test:ci

Learn more: Testing Guide

🚢 Deployment

Production-ready with Docker:

# Build image
docker build -t 2krika-backend:latest .

# Deploy with Docker Swarm
docker stack deploy -c docker-stack.yml 2krika

Features: - Multi-stage Docker builds - Docker Swarm orchestration - Rolling updates - Health checks - Prometheus monitoring - Grafana dashboards

Learn more: Deployment Guide

📊 Project Status

  • Language: TypeScript
  • Framework: NestJS
  • Architecture: Clean Architecture
  • Test Coverage: ~70%
  • Documentation: Complete

🤝 Contributing

We welcome contributions! Please read our Contributing Guide to get started.

Quick Contribution Steps

  1. Fork the repository
  2. Create feature branch: git checkout -b feature/amazing-feature
  3. Make changes following Coding Standards
  4. Write tests for new features
  5. Ensure all tests pass: pnpm test
  6. Commit using Conventional Commits
  7. Push and create Pull Request

Support

  • Documentation - Browse this site for detailed guides
  • API Documentation - Access Swagger at /api/docs when running the app

🔗 Resources

External Documentation

Ready to start? Head to the Installation Guide to set up your development environment!