🏗️📚 JengaBooks

🏗️📚 JengaBooks

Kenya-first · AI-native · Offline-first accounting platform
Built for Kenyan SMEs, accounting firms, and enterprise partners.

Features • Architecture • Tech Stack • Quick Start • API • Testing • Deployment

🌟 Overview

JengaBooks is a multi-tenant accounting SaaS purpose-built for the Kenyan market. It treats M-Pesa as a first-class citizen, automates KRA eTIMS submissions, survives offline environments, and gamifies accounting to drive daily engagement.

🎯 The 7 Pillars

🛡️ Immutable Audit & Uniqueness — Postgres RLS, eTIMS serial enforcement, fiscal period controls

📡 Offline-First Sync — Optimistic locking, NTP clock validation, token-scoped sync

📊 Adaptive Data Ingestion — M-Pesa & Bank CSV parsing with column fingerprinting

🤖 Agentic AI — 5 DeepSeek agents with auto-fallback to Suspense Account

🔌 Fault-Tolerant APIs — Sliding window circuit breaker for KRA eTIMS

🏗️ Tenant Isolation — Dynamic statement timeouts, SKIP LOCKED queries

👤 Human-in-the-Loop — Centralized DLQ, Kanban dashboard, XP gamification

✨ Features

📱 M-Pesa Integration CSV/PDF/XLSX import with smart column fingerprinting Rule-based + AI-powered auto-categorization Reconciliation engine (exact/fuzzy/amount-only matching) HITL auto-creation for low-confidence matches 3-tier confidence UI (Green ✓ / Amber ~ / Red !) Auto-post journal entries for ≥90% confidence	🧾 KRA eTIMS Invoice creation & submission KRA PIN format validation (A123456789B) Circuit breaker for KRA API failures Automatic retry with exponential backoff Queue-based async processing VAT calculation (16% Standard, 0% Exempt/Zero-rated)
🤖 AI Agents (DeepSeek V4) Reconciliation — Auto-map transactions to accounts Compliance — KRA eTIMS & IFRS validation Fraud Detection — Nightly batch anomaly scanning Advisory — Business insights & recommendations HITL Resolution — Auto-resolve simple conflicts	🎮 Gamification 50-level progression system with titles 9 achievement badges (auto-earned from activity) Sync Streak tracking Early Bird XP bonus (reports before 5th) Company-wide leaderboards Flawless Finisher trophy (lockdown ceremony)
📒 Double-Entry Ledger Full journal entry management Chart of accounts with hierarchy Fiscal period enforcement with lockdown ceremony Trial balance, P&L, balance sheet, cash flow Recurring journal entry templates Period-over-period comparison with variance	👥 Multi-Tenant RBAC 7 roles: SUPER_ADMIN → SME_OWNER Row-Level Security on every query Company switcher for multi-entity users Team management with granular permissions
🔄 Monthly Workflow 5-phase bookkeeping tracker: Data → Categorize → Reconcile → Close → Report Real-time progress bar per client Phase-by-phase action links Automated status detection from live data	📊 Reporting Profit & Loss, Balance Sheet, Cash Flow Bank-grade loan application format Period-over-period comparison CSV export with nested data handling Shareable report links (24-hour expiry) Duplicate payment detection

🏗️ Architecture

┌──────────────────────────────────────────────────────────────────┐
│                        JengaBooks Platform                        │
├────────────────────────┬─────────────────────────────────────────┤
│                        │                                         │
│    🌐 Web App (Vite)   │    📱 Mobile App (Expo/RN)              │
│    React 18 + Tailwind │    WatermelonDB + NativeWind             │
│    React Router · Axios│    Offline-first · Socket.io             │
│                        │                                         │
├────────────────────────┴─────────────────────────────────────────┤
│                    📦 Shared Package (@jengabooks/shared)           │
│            Types · Zod Schemas · RBAC Permissions · Theme Tokens   │
├──────────────────────────────────────────────────────────────────┤
│                                                                   │
│    🚀 NestJS 10 API (Stateless · RLS-enabled)                    │
│                                                                   │
│    ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐        │
│    │ Auth Module │ │ Ledger Module│ │ AI Module        │        │
│    │ JWT · Cookie│ │ Fiscal Period│ │ 5 DeepSeek Agents│        │
│    ├─────────────┤ ├──────────────┤ ├──────────────────┤        │
│    │ M-Pesa      │ │ eTIMS Module │ │ HITL Module      │        │
│    │ CSV Import  │ │ Circuit Brkr │ │ Kanban · Reviews │        │
│    └─────────────┘ └──────────────┘ └──────────────────┘        │
│                                                                   │
│    ┌──────────────────────┐  ┌──────────────────────────┐        │
│    │ Reconciliation       │  │ Batch/QA                 │        │
│    │ Matching Engine      │  │ Nightly Fraud Detection  │        │
│    └──────────────────────┘  └──────────────────────────┘        │
│                                                                   │
├────────────────────────┬─────────────────────────────────────────┤
│                        │                                         │
│   🗄️ PostgreSQL 15     │    ⚡ Redis 7 (AOF · RDB)               │
│   pgvector · RLS       │    BullMQ · Rate Limiting               │
│                        │    Circuit Breaker State                │
└────────────────────────┴─────────────────────────────────────────┘

🛠️ Tech Stack

Layer	Technology	Purpose
Runtime	Node.js 20+	JavaScript runtime with TypeScript strict mode
Backend	NestJS 10	Modular server framework with DI, guards, interceptors
Database	PostgreSQL 15 + pgvector	Primary data store with Row-Level Security
ORM	Prisma 5	Type-safe database access & migrations
Cache & Queue	Redis 7 + BullMQ	Job queues, rate limiting, circuit breaker state
AI	DeepSeek V4	5 specialized AI agents (Pro + Flash models)
Web Frontend	React 18 + Vite + TailwindCSS	SPA dashboard with responsive design
Mobile	Expo 51 + NativeWind	Cross-platform mobile app
Offline DB	WatermelonDB	Local-first sync database for mobile
Real-time	Socket.io	Live notifications & sync events
Auth	JWT + httpOnly Cookies	Stateless auth with refresh token rotation
Monorepo	Turborepo	Workspace orchestration & caching
Testing	Jest 29 + Supertest	Unit, integration, and E2E testing

📁 Project Structure

jengabooks/
│
├── apps/
│   ├── api/                    # 🚀 NestJS Backend
│   │   ├── prisma/             # Schema, migrations, seeds
│   │   └── src/
│   │       ├── common/         # Decorators, filters, interceptors
│   │       ├── config/         # Database, Redis configuration
│   │       ├── modules/        # Feature modules (13 total)
│   │       │   ├── auth/       # JWT auth, refresh, switch-company
│   │       │   ├── ledger/     # Journal entries, accounts, periods, recurring
│   │       │   ├── mpesa/      # CSV/PDF import, categorization, file parser
│   │       │   ├── etims/      # KRA invoice submission, circuit breaker
│   │       │   ├── ai/         # 5 DeepSeek AI agents + batch service
│   │       │   ├── hitl/       # Human-in-the-Loop reviews
│   │       │   ├── gamification/# XP, levels, badges, streaks, leaderboard
│   │       │   ├── reports/    # P&L, Balance Sheet, Cash Flow, comparisons
│   │       │   ├── reconciliation/ # Transaction matching engine
│   │       │   ├── sync/       # Offline sync endpoints
│   │       │   ├── tenants/    # Multi-tenant management
│   │       │   ├── wizard/     # Onboarding wizard
│   │       │   ├── health-score/ # Business health scoring
│   │       │   └── workflow/   # Workflow dashboard logic
│   │       ├── prisma/         # Prisma service module
│   │       ├── queues/         # BullMQ queue definitions
│   │       └── e2e/            # End-to-end integration tests
│   │
│   ├── web/                    # 🌐 Web Frontend
│   │   └── src/
│   │       ├── components/     # UI components, forms, layout
│   │       ├── pages/          # Route pages (13 routes)
│   │       ├── hooks/          # React Query hooks
│   │       ├── stores/         # Zustand state stores
│   │       └── lib/            # API client, types, utils
│   │
│   └── mobile/                 # 📱 Mobile App
│       └── src/
│           ├── app/            # Expo Router pages
│           ├── components/     # Mobile UI components
│           ├── hooks/          # Mobile hooks
│           ├── stores/         # Mobile state stores
│           └── lib/            # API client, offline DB
│
├── packages/
│   └── shared/                 # 📦 Shared Package
│       └── src/                # Types, Zod schemas, RBAC, theme, helpers
│
├── plans/                      # 📋 Architecture plans & audit docs
├── docker-compose.yml          # 🐳 Local dev (Postgres + Redis)
├── turbo.json                  # ⚡ Turborepo configuration
└── package.json                # 📋 Monorepo root

🚀 Quick Start

Choose your environment below.

🐧 Option A: Linux Native (PostgreSQL + Redis on host)

Best for: Linux workstations, CI/CD runners, production servers.

Prerequisites

Tool	Version	Check
Node.js	>= 20.0.0	`node --version`
npm	11.x	`npm --version`
PostgreSQL	15+	`psql --version`
Redis	7+	`redis-cli --version`

Setup

# 1. Clone & install
git clone https://github.com/Jpkoech30/jengabooks.git
cd jengabooks
npm install

# 2. Configure environment
cp .env.example apps/api/.env

# 3. Create the database
sudo -u postgres psql -c "CREATE DATABASE jengabooks;"

# 4. Run database migrations
cd apps/api && npx prisma migrate dev

# 5. Seed demo data
npx ts-node prisma/seed.ts

# 6. Start development (from root)
cd ../.. && npm run dev

Connection config (.env / apps/api/.env):

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/jengabooks?schema=public"
REDIS_HOST=localhost
REDIS_PORT=6379

🐳 Option B: Windows + Docker (PostgreSQL + Redis in containers)

Best for: Windows workstations with Docker Desktop.

Prerequisites

Tool	Version	Check
Node.js	>= 20.0.0	`node --version`
npm	11.x	`npm --version`
Docker Desktop	Latest	`docker --version`

Setup

# 1. Clone & install
git clone https://github.com/Jpkoech30/jengabooks.git
cd jengabooks
npm install

# 2. Configure environment
cp .env.example apps/api/.env

# 3. Start infrastructure (Docker)
docker-compose up -d

# 4. Run database migrations
cd apps/api && npx prisma migrate dev

# 5. Seed demo data
npx ts-node prisma/seed.ts

# 6. Start development (from root)
cd ../.. && npm run dev

Connection config (.env / apps/api/.env):

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/jengabooks?schema=public"
REDIS_HOST=localhost
REDIS_PORT=6379

Docker Desktop on Windows maps container ports to localhost by default — no special config needed.

🪟 Option C: Windows + WSL (PostgreSQL + Redis inside WSL)

Best for: Windows workstations running services natively in WSL without Docker.

Prerequisites

Tool	Version	Check	Where
Node.js	>= 20.0.0	`node --version`	Windows
npm	11.x	`npm --version`	Windows
WSL distro	Ubuntu 24.04+	`wsl -l -v`	Windows
PostgreSQL	15+	`psql --version`	WSL (inside distro)
Redis	7+	`redis-cli --version`	WSL (inside distro)

⚠️ Important: Node.js runs on Windows, while PostgreSQL and Redis run inside WSL. This means localhost from Node.js on Windows does not reliably forward to WSL services. You must use the WSL instance's network IP.

Step 1: WSL Infrastructure Setup

# Inside WSL — Install PostgreSQL
sudo apt update
sudo apt install -y postgresql postgresql-client redis-server

# Start services
sudo service postgresql start
sudo service redis-server start

# Configure PostgreSQL for external connections
sudo sed -i "s/#listen_addresses = 'localhost'/listen_addresses = '*'/" /etc/postgresql/15/main/postgresql.conf
sudo sed -i "s/127.0.0.1\/32/0.0.0.0\/0/" /etc/postgresql/15/main/pg_hba.conf
sudo service postgresql restart

# Create the database
sudo -u postgres psql -c "CREATE DATABASE jengabooks;"

Step 2: Find your WSL IP

# From Windows PowerShell
wsl -- ip addr | findstr "inet "
# Look for an address like 192.168.1.XXX (not 127.0.0.1 or inet6)

Step 3: Configure Connection

# On Windows — Clone & install
git clone https://github.com/Jpkoech30/jengabooks.git
cd jengabooks
npm install

# Configure .env with the WSL IP found above
# Edit .env and apps/api/.env

Connection config (.env / apps/api/.env):

# ❌ Will NOT work:
# DATABASE_URL="postgresql://postgres:postgres@localhost:5432/jengabooks"

# ✅ Use WSL's real IP — disable SSL (local Postgres doesn't need it):
DATABASE_URL="postgresql://postgres:postgres@192.168.1.180:5432/jengabooks?schema=public&sslmode=disable"
REDIS_HOST=localhost
REDIS_PORT=6379

Why localhost fails: Windows' WSL2 port forwarding is unreliable on some configurations. The WSL instance gets a virtual IP that is stable within a session but localhost does not always forward correctly. Direct IP connection with SSL disabled is the confirmed working configuration.

Step 4: Run Migrations & Seed

cd apps/api
npx prisma migrate dev
npx ts-node prisma/seed.ts
cd ../..
npm run dev

Step 5: Verify Connection

# From the project root — tests both WSL IP and localhost
node scripts/test-conn2.js

# Expected output:
# ✓ WSL IP: [{"db":"jengabooks","ver":"PostgreSQL 18.4..."}]
# ✗ localhost: Can't reach database server at localhost:5432

Automation: One-command start

The dev launcher script handles everything automatically:

.\scripts\dev.ps1

What it does:

Starts WSL (if not running)
Starts PostgreSQL and Redis in WSL
Auto-detects the WSL IP and injects it into DATABASE_URL at runtime
Waits for PostgreSQL and Redis to be ready (retries up to 15 times)
Checks optional 3rd party API connectivity (DeepSeek, KRA eTIMS)
Starts the JengaBooks dev server

Expected output:

=== JengaBooks Dev Environment ===

[1/5] Checking WSL status...
  ✓ WSL is ready
[2/5] Starting PostgreSQL...
  ✓ PostgreSQL already running
[3/5] Starting Redis...
  ✓ Redis already running
[4/5] Detecting WSL IP and configuring connection...
  ✓ DATABASE_URL configured with WSL IP
    → postgresql://postgres:postgres@192.168.1.180:5432/jengabooks?schema=public&sslmode=disable
[5/5] Verifying service connectivity...
  ✓ PostgreSQL is ready
  ✓ Redis is ready
  - DeepSeek AI API: skipped (no API key configured)
  - KRA eTIMS API: skipped (no KRA_API_URL configured)
  ✅ All services are ready! Starting application...

Options:

# Skip the service health check (faster startup)
.\scripts\dev.ps1 -SkipServiceCheck

# Skip WSL steps entirely (for Docker or Linux)
.\scripts\dev.ps1 -SkipWsl

# Specify a different WSL distro
.\scripts\dev.ps1 -WslDistro Ubuntu-22.04

How IP injection works: The script runs node scripts/wsl-ip.js --export which outputs $env:DATABASE_URL="postgresql://...@<detected-ip>...". This env var overrides whatever is in the .env file, so you never need to edit .env when the WSL IP changes.

If WSL IP Changes (manual fallback)

WSL's IP can change after a reboot. If you're not using dev.ps1, find the new IP:

wsl -- ip addr | findstr "inet "

Then update DATABASE_URL in both:

Or better, use the automated script:

# This detects the IP and exports the correct DATABASE_URL for the current session
$env:DATABASE_URL = "$(node scripts/wsl-ip.js --export)"
npm run dev

🔐 Demo Credentials

Role	Email	Password
Firm Owner	`admin@jengabooks.com`	`password123`

🧪 Testing

The project has 234 tests across 24 test suites.

Test Types

Type	Count	What It Tests
Unit (pure logic)	~120	Static methods, DTO validation, calculations, level thresholds, file parsing
Integration (mocked DB)	~100	Services with mocked Prisma: auth, ledger, HITL, reports, reconciliation
E2E (HTTP + real DB)	14	Full request/response cycle: register, login, auth flows

Test Coverage by Module

Module	Tests	Key Features Tested
Auth	16	Login, register, refresh, profile, DTO validation
Ledger	34	Accounts CRUD, journal entries, trial balance, serial numbers, recurring entries, lockdown
eTIMS	22	Invoices, VAT, KRA PIN validation, submissions, circuit breaker
M-Pesa	75	CSV parsing, file formats, bank templates, AI agents, auto-post, bulk approve, upload validation
HITL	7	Create, assign, resolve with XP
Reports	24	P&L, Balance Sheet, Cash Flow, period comparison, duplicates, share tokens
Gamification	20	Level calculation, sync streaks, early bird, level-up detection
Tenants	6	CRUD, member management, invite
Wizard	6	Progress tracking, step completion
AI Batch	5	Nightly fraud detection
Exception Filter	6	Prisma errors, HTTP errors
Circuit Breaker	6	State transitions, timeout, reset
Confidence Tier	8	3-tier confidence logic
Reconciliation	11	Matching engine (exact/fuzzy), status
Workflow	5	5-phase progress calculation
Total	234

Running Tests

# All unit + integration tests
cd apps/api && npm test

# Watch mode
cd apps/api && npm run test:watch

# With coverage
cd apps/api && npm run test:cov

# Specific module
cd apps/api && npx jest --verbose --testPathPattern="mpesa"

# E2E tests (requires database)
cd apps/api && npx jest --config jest-e2e.config.ts

🌐 API Reference

All endpoints are prefixed with /api/v1 and protected with JWT authentication (except login & register).

🔑 Auth

Method	Endpoint	Description
`POST`	`/api/v1/auth/login`	Sign in with email + password (5 req/min)
`POST`	`/api/v1/auth/register`	Create account + company (3 req/min)
`POST`	`/api/v1/auth/refresh`	Refresh JWT token
`POST`	`/api/v1/auth/logout`	Clear session
`GET`	`/api/v1/auth/profile`	Get user profile + memberships
`POST`	`/api/v1/auth/switch-company`	Switch active company

📒 Ledger

Method	Endpoint	Description
`GET`	`/api/v1/ledger/accounts`	List chart of accounts
`POST`	`/api/v1/ledger/accounts`	Create account
`GET`	`/api/v1/ledger/entries`	List journal entries
`POST`	`/api/v1/ledger/entries`	Create journal entry
`POST`	`/api/v1/ledger/transactions/income`	Quick income entry
`POST`	`/api/v1/ledger/transactions/expense`	Quick expense entry
`GET`	`/api/v1/ledger/trial-balance`	Trial balance report
`GET`	`/api/v1/ledger/periods`	Fiscal periods

💰 M-Pesa

Method	Endpoint	Description
`POST`	`/api/v1/mpesa/import`	Import CSV/XLSX/PDF transactions
`GET`	`/api/v1/mpesa`	List transactions
`POST`	`/api/v1/mpesa/:txId/map`	Map to account

🧾 eTIMS

Method	Endpoint	Description
`GET`	`/api/v1/etims/invoices`	List invoices
`POST`	`/api/v1/etims/invoices`	Create invoice
`POST`	`/api/v1/etims/submissions/:id/submit`	Submit to KRA

🤖 AI

Method	Endpoint	Description
`POST`	`/api/v1/ai/process`	Trigger AI processing
`POST`	`/api/v1/ai/feedback`	Submit feedback
`POST`	`/api/v1/ai/batch/fraud-detection`	Manual fraud batch run

👤 HITL (Human-in-the-Loop)

Method	Endpoint	Description
`GET`	`/api/v1/hitl`	List reviews (with filters)
`POST`	`/api/v1/hitl`	Create review
`POST`	`/api/v1/hitl/:id/assign`	Claim task
`POST`	`/api/v1/hitl/:id/resolve`	Resolve with action + XP

🏆 Gamification

Method	Endpoint	Description
`GET`	`/api/v1/gamification/profile`	User XP, level, badges
`GET`	`/api/v1/gamification/badges`	Earned & available badges
`GET`	`/api/v1/gamification/leaderboard`	Company ranking

📊 Reports

Method	Endpoint	Description
`GET`	`/api/v1/reports/profit-loss`	Profit & Loss statement
`GET`	`/api/v1/reports/balance-sheet`	Balance sheet
`GET`	`/api/v1/reports/trial-balance`	Trial balance
`GET`	`/api/v1/reports/cash-flow`	Cash flow statement

📋 Workflow

Method	Endpoint	Description
`GET`	`/api/v1/workflow`	Monthly workflow progress (all 5 phases)

🎮 Gamification System

Level Progression

Level Range	Title	XP Required
1–5	🪜 Apprentice	0 – 1,000
6–10	📚 Bookkeeper	1,500 – 4,500
11–20	🧮 Accountant	5,500 – 19,000
21–30	💼 Finance Pro	21,000 – 43,500
31–50	🏆 Business Master	46,500 – 122,500

Badges

Badge	Trigger	XP
📚 Accountant	Set up Chart of Accounts (5+ accounts)	25
📱 M-Pesa Connected	M-Pesa transactions exist	25
📊 Data Driven	Import first M-Pesa CSV	25
💰 First Income	Record first income	25
💳 First Expense	Record first expense	25
🛡️ Tax Compliant	Submit first eTIMS invoice (ACCEPTED)	50
👥 Team Player	Invite a team member	25
📈 Analyst	Generate first report (5+ entries)	25
🤖 Trust the AI	Bulk approve 10+ AI-categorized transactions	25

Streaks & Bonuses

Mechanic	Trigger	Reward
Sync Streak	Consecutive days of activity	Badge at 7/30/90 days
Early Bird	Submit reports before 5th of month	+50 XP
Flawless Finisher	Complete lockdown with 0 errors	Trophy badge

👥 RBAC Roles

Role	Level	Description
`SUPER_ADMIN`	🔴 Platform	Full system access, DevOps
`FIRM_OWNER`	🟣 Partner	Accounting firm ownership
`TENANT_ADMIN`	🟠 Admin	Tenant internal administration
`ACCOUNTANT`	🔵 Staff	Daily accounting operations
`SME_OWNER`	🟢 Business	SME business owner view
`AUDITOR`	🟡 External	Read-only audit access
`BANK_OFFICER`	⚪ Loan	Loan portfolio view

🔧 Environment Variables

Variable	Required	Default	Description
`DATABASE_URL`	✅	—	PostgreSQL connection string
`PORT`	❌	`3000`	API server port
`JWT_SECRET`	✅	—	JWT signing secret
`REDIS_HOST`	❌	`localhost`	Redis host
`REDIS_PORT`	❌	`6379`	Redis port
`DEEPSEEK_API_KEY`	⚠️	—	Required for AI features
`KRA_API_URL`	❌	—	KRA eTIMS API endpoint (mock used if unset)
`KRA_CLIENT_ID`	⚠️	—	Required for eTIMS
`CORS_ORIGIN`	❌	`http://localhost:5173`	Allowed CORS origin

☁️ Deployment

Tier 1 — Single VM (Vultr Johannesburg)

docker-compose -f docker-compose.prod.yml up -d

Tier 2 — Horizontal Scaling

Vultr Load Balancer
    ├── Node.js VM 1 (API + Web)
    ├── Node.js VM 2 (API + Web)
    └── Node.js VM n (Workers)

Tier 3 — High Availability

Vultr Managed PostgreSQL → Replica set
Vultr Managed Redis      → Cluster
Vultr Object Storage     → Backups

Environment Configuration for Production

# Required for production
NODE_ENV=production
JWT_SECRET=<strong-random-secret>
DATABASE_URL=postgresql://user:password@vultr-db:5432/jengabooks

# For AI features (optional, degrades gracefully if unset)
DEEPSEEK_API_KEY=sk-your-key
KRA_API_URL=https://kra-api.go.ke/v1
KRA_CLIENT_ID=your-client-id

📚 Additional Documentation

Document	Location	Description
Audit Report	`plans/jengabooks-comprehensive-audit.md`	Full project audit with 24 issues
Test Strategy	`plans/jengabooks-test-strategy.md`	158-test plan across 5 phases
Workflow Spec	`plans/acct-workflow-gap-analysis.md`	Kenyan accounting workflow specification
Gap Analysis	`plans/acct-workflow-roadmap.md`	6-phase implementation roadmap
Pricing Spec	`plans/accontingspecs.md`	Full accounting feature specification

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feat/amazing-feature)
Commit changes (git commit -m 'feat: add amazing feature')
Push to branch (git push origin feat/amazing-feature)
Open a Pull Request

Before submitting: Run the test suite and ensure all tests pass.

cd apps/api && npm test

📄 License

Built with 💚 for Kenyan businesses
_{Nairobi · Mombasa · Kisumu · Eldoret}

Name		Name	Last commit message	Last commit date
Latest commit History 179 Commits
apps		apps
packages/shared		packages/shared
plans		plans
scripts		scripts
.env		.env
.env.example		.env.example
.gitignore		.gitignore
.project-context.json		.project-context.json
.roomodes		.roomodes
AGENT-FLOW.md		AGENT-FLOW.md
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
README.md		README.md
docker-compose.yml		docker-compose.yml
fix_schema.ps1		fix_schema.ps1
package-lock.json		package-lock.json
package.json		package.json
security-report.md		security-report.md
tsconfig.base.json		tsconfig.base.json
tsconfig.json		tsconfig.json
turbo.json		turbo.json
violations-report.md		violations-report.md
{})		{})

Folders and files

Latest commit

History

Repository files navigation

🏗️📚 JengaBooks

🌟 Overview

✨ Features

📱 M-Pesa Integration

🧾 KRA eTIMS

🤖 AI Agents (DeepSeek V4)

🎮 Gamification

📒 Double-Entry Ledger

👥 Multi-Tenant RBAC

🔄 Monthly Workflow

📊 Reporting

🏗️ Architecture

🛠️ Tech Stack

📁 Project Structure

🚀 Quick Start

🐧 Option A: Linux Native (PostgreSQL + Redis on host)

Prerequisites

Setup

🐳 Option B: Windows + Docker (PostgreSQL + Redis in containers)

Prerequisites

Setup

🪟 Option C: Windows + WSL (PostgreSQL + Redis inside WSL)

Prerequisites

Step 1: WSL Infrastructure Setup

Step 2: Find your WSL IP

Step 3: Configure Connection

Step 4: Run Migrations & Seed

Step 5: Verify Connection

Automation: One-command start

If WSL IP Changes (manual fallback)

🔐 Demo Credentials

🔐 Demo Credentials

🧪 Testing

Test Types

Test Coverage by Module

Running Tests

🌐 API Reference

🔑 Auth

📒 Ledger

💰 M-Pesa

🧾 eTIMS

🤖 AI

👤 HITL (Human-in-the-Loop)

🏆 Gamification

📊 Reports

📋 Workflow

🎮 Gamification System

Level Progression

Badges

Streaks & Bonuses

👥 RBAC Roles

🔧 Environment Variables

☁️ Deployment

Tier 1 — Single VM (Vultr Johannesburg)

Tier 2 — Horizontal Scaling

Tier 3 — High Availability

Environment Configuration for Production

📚 Additional Documentation

🤝 Contributing

📄 License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages