Project Structure

This document explains the file and folder organization of the 2KRIKA project.

Root Directory

2krika/
├── adapters/           # Infrastructure implementations
├── app/                # Application use cases and logic
├── domain/             # Core business entities and rules
├── web/                # NestJS HTTP/WebSocket layer
├── shared/             # Cross-cutting concerns
├── tests/              # Test suites
├── docs/               # Documentation
├── migrations/         # Database migrations (empty, using Sequelize)
├── storage/            # File uploads (gitignored)
├── logs/               # Application logs (gitignored)
├── package.json        # Dependencies and scripts
├── tsconfig.json       # TypeScript configuration
├── jest.config.ts      # Test configuration
├── Dockerfile          # Container definition
└── docker-compose.yml  # Multi-container setup (gitignored)

Layer Breakdown

Domain Layer (domain/)

Pure business logic with no external dependencies.

domain/
├── accounts/           # Account entities and rules
│   ├── account.entity.ts
│   ├── account.repository.ts
│   └── account_event.repository.ts
├── orders/             # Order entities and workflow
│   ├── order.entity.ts
│   ├── order.repository.ts
│   ├── chat.entity.ts
│   ├── chat.repository.ts
│   └── comment.repository.ts
├── payments/           # Payment abstractions
│   ├── payment.gateway.ts
│   └── payment_event.repository.ts
├── service/            # Service catalog entities
│   ├── service.entity.ts
│   ├── service.repository.ts
│   ├── category.entity.ts
│   └── category.repository.ts
├── transactions/       # Transaction entities
│   └── transaction.repository.ts
├── user/               # User entities and permissions
│   ├── user.entity.ts
│   ├── user.repository.ts
│   ├── permission.vo.ts
│   └── portfolio.repository.ts
└── shared/             # Shared domain concepts
    └── repository/
        ├── base.ts
        ├── pagination.ts
        └── exceptions.ts

Key characteristics: - Abstract classes and interfaces - Pure TypeScript (no decorators) - Business rules as methods - No framework imports

Application Layer (app/)

Orchestrates domain entities to implement use cases.

app/
├── accounts/           # Account use cases
│   ├── account.usecases.ts
│   ├── refund.usecases.ts
│   ├── withdraw.usecases.ts
│   └── *.validators.ts
├── order/              # Order use cases
│   ├── usecases.ts
│   ├── chat.usecases.ts
│   ├── comment.usecases.ts
│   ├── payment.usecases.ts
│   ├── workflow.ts
│   ├── order.task.ts
│   └── *.validators.ts
├── service/            # Service use cases
│   ├── usecases.ts
│   ├── category.usecases.ts
│   ├── option.usecases.ts
│   └── validators.ts
├── user/               # User use cases
│   ├── usecases.ts
│   ├── identity.usecases.ts
│   ├── kyc.usecases.ts
│   ├── portfolio.usecases.ts
│   └── *.validators.ts
├── shared/             # Shared application logic
│   ├── cache.ts
│   ├── exceptions.ts
│   ├── filesystem.ts
│   ├── pagination.ts
│   ├── repositories.ts
│   ├── storage.ts
│   ├── validator.ts
│   └── utils.ts
├── utils/              # Helper utilities
└── config.ts           # Application configuration

Key characteristics: - Use case functions - Zod validators - DTO transformations - Framework-agnostic

Adapters Layer (adapters/)

Implements domain interfaces for external systems.

adapters/
├── account/            # Account data access
│   ├── account.repository.ts
│   ├── account_event.repository.ts
│   ├── refund.repository.ts
│   └── withdraw.repository.ts
├── order/              # Order data access
│   ├── order.repository.ts
│   ├── order.workflow.ts (XState machine)
│   ├── payment.repository.ts
│   ├── paystack.gateway.ts
│   └── chat.repository.ts
├── service/            # Service data access
│   ├── service.repository.ts
│   ├── category.repository.ts
│   ├── comment.repository.ts
│   └── serviceview.repository.ts
├── transaction/        # Transaction data access
│   └── transaction.repository.ts
├── user/               # User data access
│   ├── user.repository.ts
│   ├── identity.repository.ts
│   ├── userrole.repository.ts
│   └── portfolio.repository.ts
├── storage/            # File storage
│   ├── local.ts
│   └── upload.repository.ts
└── shared/             # Shared adapter logic
    ├── db.ts           # Database setup
    ├── cache/
    │   └── redis.ts
    ├── mongo/
    │   └── models/
    ├── sql/
    │   ├── models/     # Sequelize models
    │   ├── migrations/ # Database migrations
    │   └── seeders/    # Seed data
    └── repository/
        └── sql.ts      # Base SQL repository

Key characteristics: - SQL/NoSQL implementations - External API integrations - Concrete repository classes - Framework-specific code allowed

Web Layer (web/)

NestJS modules, controllers, and HTTP handling.

web/
├── accounts/           # Account endpoints
│   ├── accounts.module.ts
│   └── accounts.controller.ts
├── auth/               # Authentication
│   ├── auth.module.ts
│   ├── auth.controller.ts
│   ├── auth.service.ts
│   └── auth.guard.ts
├── orders/             # Order endpoints
│   ├── orders.module.ts
│   ├── orders.controller.ts
│   ├── orders.service.ts
│   ├── chat.controller.ts
│   ├── chat.gateway.ts (WebSocket)
│   └── payments.controller.ts
├── services/           # Service endpoints
│   ├── services.module.ts
│   ├── services.controller.ts
│   └── categories.controller.ts
├── users/              # User endpoints
│   ├── users.module.ts
│   ├── users.controller.ts
│   └── kyc.controller.ts
├── stats/              # Statistics endpoints
│   ├── stats.module.ts
│   └── stats.controller.ts
├── config/             # Config endpoints
│   ├── config.module.ts
│   └── config.controller.ts
├── shared/             # Shared web utilities
│   └── renderers/
│       └── pdf.ts
├── app.module.ts       # Root module
├── main.ts             # Application entry point
├── http-exception.filter.ts
├── types.ts
└── utils.ts

Key characteristics: - NestJS decorators - HTTP request/response handling - Dependency injection - Guards and filters

Shared Layer (shared/)

Cross-cutting concerns used across layers.

shared/
├── logging/
│   ├── base.ts         # Abstract logger
│   └── file.ts         # File logger implementation
└── notifications/
    ├── base.ts         # Abstract notifier
    └── email.ts        # Email notifier implementation

Tests (tests/)

Comprehensive test suites mirroring the main structure.

tests/
├── adapters/           # Adapter tests
├── app/                # Use case tests
├── domain/             # Entity tests
├── web/                # Controller tests
├── shared/             # Shared logic tests
├── mocks/              # Mock implementations
├── data/               # Test data
├── factories.ts        # Test factories
└── utils.ts            # Test utilities

File Naming Conventions

Type	Pattern	Example
Entity	*.entity.ts	user.entity.ts
Repository Interface	*.repository.ts (in domain)	user.repository.ts
Repository Implementation	*.repository.ts (in adapters)	user.repository.ts
Use Cases	*.usecases.ts or usecases.ts	user.usecases.ts
Validators	*.validators.ts or validators.ts	user.validators.ts
DTOs	*.dto.ts or usecases.dto.ts	service.usecases.dto.ts
Controllers	*.controller.ts	users.controller.ts
Modules	*.module.ts	users.module.ts
Services	*.service.ts	auth.service.ts
Guards	*.guard.ts	auth.guard.ts
Gateways	*.gateway.ts	chat.gateway.ts
Tests	*.test.ts	user.entity.test.ts

Import Path Aliases

The project uses path aliases for cleaner imports:

// Instead of
import { User } from '../../../domain/user/user.entity';

// Use
import { User } from '@/domain/user/user.entity';

Configured in tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

Configuration Files

File	Purpose
package.json	Dependencies and scripts
tsconfig.json	TypeScript compiler options
tsconfig.build.json	Production build configuration
jest.config.ts	Test runner configuration
eslint.config.mjs	Linting rules
Dockerfile	Container image definition
.gitignore	Git ignore rules

Next Steps

• Design Principles
• Technology Stack
• Core Concepts