StockKit

Multi-tenant Business Operations Platform for Indonesian Companies

Quick Start • Features • Architecture • API Docs • Frontend • Contributing

---

Multi-tenant Business Operations Platform for Indonesian Companies

Quick Start • Features • Architecture • API Docs • Frontend • Contributing

---

📖 Overview

StockKit is a production-grade, multi-tenant ERP-like platform built for Indonesian businesses — from UMKM to project-based enterprises. It covers the complete business cycle: inventory → purchasing → sales → finance → reporting, with built-in approval workflows, FX rate management, and a developer-focused observability suite.

Designed for: Indonesian companies needing localized tax IDs (NPWP), IDR-first accounting, BPJS-ready payroll hooks, and regulatory-compliant audit trails.

---

✨ Features

🗂️ Core Modules

Module	Description
📦 Inventory	Multi-warehouse stock levels, FIFO/Average costing, adjustments, movements with full audit trail
🛒 Purchasing	Purchase requests → approval → PO → goods receipt → supplier invoice flow
💰 Sales	Sales orders → checkout (reserve) → deliver → invoice → receipt (cash flow)
🏦 Finance	Cash accounts, multi-currency payments, AR/AP aging, net working capital
📊 Reports	P&L, inventory valuation, AR/AP aging, digital signature on PDF export
🌐 FX Rates	Daily rate management with automatic document conversion
✅ Approvals	Multi-step approval workflows with threshold-based rules
👥 Users & Roles	8 RBAC roles: developer, owner, admin, finance, sales, purchasing, warehouse, auditor

🎨 UX Highlights

• Theme-aware UI — Light / Dark / System with design tokens
• Signature Pad — Canvas-based digital signature for PDF reports (localStorage reuse)
• Matrix Rain — Developer suite accent (role-gated)
• Auto-refresh charts — Real-time observability (5s interval, role-gated)
• Mobile-ready — Responsive sidebar with Ctrl+B collapse shortcut

🔒 Security & Compliance

• AES-256-GCM encryption for supplier bank accounts
• JWT refresh token rotation with reuse detection
• CSRF protection on all state-changing endpoints
• Structured colored logs with PII redaction (password, token, credit card)
• Daily log rotation (.log colored + .jsonl machine-readable)

---

🏗️ Architecture

flowchart TB
    subgraph Client[Frontend Layer]
        UI[Next.js 16 UI]
        API_Client[API Client + Auto-Refresh]
        WS[WebSocket Singleton]
    end

    subgraph Server[Backend Layer]
        Chi[Chi Router + Middleware]
        Handlers[Handlers]
        Services[Business Services]
        Repositories[Repositories]
        RT[Realtime Hub]
        AuditListener[Audit LISTEN]
        ProfileListener[Profile LISTEN]
    end

    subgraph Data[Data Layer]
        PG[(PostgreSQL 18)]
        Redis[(Redis 7)]
        MinIO[(MinIO S3)]
        Logs[./logs/]
    end

    UI -->|HTTPS| Chi
    API_Client -->|Bearer + CSRF| Chi
    WS <-->|WebSocket| RT
    Chi -->|AuthN + CSRF + Logging| Handlers
    Handlers --> Services
    Services --> Repositories
    Repositories --> PG
    Repositories --> Redis
    Repositories --> MinIO
    Handlers --> Logs
    PG -->|pg_notify audit_events| AuditListener
    PG -->|pg_notify user_profile_events| ProfileListener
    AuditListener --> RT
    ProfileListener --> RT
    RT --> WS

Loading

Tech Stack

Layer	Technology	Purpose
Frontend	Next.js 16.3.6, React 19, TypeScript, Tailwind CSS, Recharts, Framer Motion	SPA, charts, animations
Backend	Go 1.27.1, Chi router, pgx v5, slog, golang-migrate	REST API, migrations, structured logging
Database	PostgreSQL 18.6	OLTP, ACID transactions
Cache	Redis 7	Sessions, rate limiting (graceful degradation)
Storage	MinIO (S3-compatible)	Product images, user avatars
Infra	Docker Compose	Local dev orchestration

---

🚀 Quick Start

Prerequisites

• Go 1.27.1+
• Node.js 20+
• Docker & Docker Compose
• Git

Installation

# Clone
git clone https://github.com/neuralforgeio/StockKit.git
cd StockKit

# Environment
cd backend
cp .env.example .env
# Edit .env — set POSTGRES_PASSWORD, JWT_EDDSA_KEY, FIELD_ENCRYPTION_KEY (see .env.example)

# Start PostgreSQL (if not using Docker)
# Or: docker compose up -d

# Backend
go mod tidy
go run ./cmd/api migrate up
go run ./cmd/api seed          # seeds tenant, roles, developer user, initial data
go run ./cmd/api serve         # :8080

# Frontend (separate terminal)
cd frontend
npm install
npm run dev                    # :3000

Bootstrap User (Alternative So Seed)

# Interactive prompts (password hidden, zero leak)
# -> Email: admin@company.com
# -> Password: ********
# -> Confirm Password: ********

CLI Commands

go run ./cmd/api serve        # Start API server
go run ./cmd/api migrate up   # Run pending migrations
go run ./cmd/api migrate down # Rollback last migration
go run ./cmd/api migrate version  # Show current version
go run ./cmd/api seed         # Seed initial data (idempotent)
go run ./cmd/api version      # Show build info

---

📚 Documentation

Document	Description
📘 API Reference	Complete REST API documentation with request/response examples
🎨 Frontend Guide	Page structure, routing, component patterns
🏛️ Architecture	Deep-dive into modules, data flow, decisions
🚢 Deployment	Production deployment & security hardening
🔐 Security	Auth flow, encryption, redaction, CSRF
🔍 Audit System	Realtime audit logs, LISTEN/NOTIFY, diff formatter, UUID resolution
👥 User Management	User lifecycle, RBAC, audit trail, bootstrap CLI

---

🔄 Business Flow Example

sequenceDiagram
    participant U as Sales User
    participant SO as Sales Orders
    participant A as Approvals
    participant I as Inventory
    participant F as Finance

    U->>SO: Create draft SO
    U->>SO: Submit for approval
    SO->>A: Create approval instance
    A-->>U: Notify approver

    Note over A: Approval required when amount is at or above threshold

    A->>A: Approver reviews and decides
    A-->>SO: Status becomes approved

    SO->>I: Checkout and reserve stock
    SO->>I: Deliver goods and record OUT movement
    SO->>F: Create customer invoice and record AR
    F->>F: Record customer receipt

Loading

---

📂 Project Structure

StockKit/
├── backend/
│   ├── cmd/api/              # Main entry point (serve, migrate, seed, version)
│   ├── internal/
│   │   ├── approval/         # Multi-step approval workflows
│   │   ├── auth/             # JWT, EdDSA signing, refresh rotation
│   │   ├── categories/       # Product categories (hierarchical)
│   │   ├── codes/            # Sequential number allocator
│   │   ├── config/           # Environment config
│   │   ├── crypto/           # AES-256-GCM field cipher
│   │   ├── customers/        # Customer master data
│   │   ├── dashboard/        # Aggregated KPIs
│   │   ├── devutil/          # OS disk usage (windows/unix)
│   │   ├── finance/          # Cash accounts, payments
│   │   ├── fx/               # FX rates
│   │   ├── httpapi/          # Router, handlers, middleware
│   │   ├── inventory/        # Stock levels, movements, COGS
│   │   ├── invoices/         # Supplier invoices, payments
│   │   ├── logging/          # Colored rotating structured logs
│   │   ├── notify/           # In-app notifications
│   │   ├── products/         # Product catalog
│   │   ├── purchasing/       # Purchase requests, PO, goods receipts
│   │   ├── sales/            # Sales orders, customer invoices, receipts
│   │   ├── store/            # pg pool, redis client
│   │   ├── suppliers/        # Supplier master (encrypted bank accounts)
│   │   ├── units/            # Product units
│   │   └── warehouses/       # Warehouse master
│   └── migrations/           # SQL migrations
├── frontend/
│   ├── app/                  # Next.js app router pages
│   ├── components/           # UI primitives + layout
│   └── lib/                  # API client, utils, export (PDF/Excel)
├── docs/                     # Documentation
├── infra/postgres/initdb/    # Database init scripts
└── docker-compose.yml        # Local dev orchestration

---

🎯 Roadmap

✅ Completed (M1-M6)

• Platform foundation (API, auth, migrations)
• Master data: products, categories, units, warehouses, customers, suppliers
• Inventory: stock levels, movements, adjustments, FIFO/Average costing
• Purchasing: requests → PO → goods receipt → supplier invoice
• Sales: orders → checkout → deliver → invoice → receipt
• Finance: cash accounts, payments, FX rates
• Approvals: multi-step workflow with threshold rules
• Reports: P&L, inventory valuation, AR/AP aging, PDF/Excel export
• Developer suite: metrics, analytics, disk monitor, live logs
• RBAC: sidebar gating for developer-only features

🚧 In Progress (M7)

• Approval decided hook (sync document status on approve/reject)
• Multi-currency auto-conversion on documents
• Goods receipts UI polish

📅 Planned (M8+)

• BPJS/Tax integrations
• Advanced forecasting (inventory demand)
• Mobile app (React Native)
• Webhook system for external integrations
• Audit log viewer (immutable, filterable)

---

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m "feat(module): description")
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Commit Convention

We follow Conventional Commits:

• feat: — new features
• fix: — bug fixes
• docs: — documentation only
• refactor: — code refactoring
• perf: — performance improvements
• test: — adding tests
• chore: — maintenance tasks

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

🙏 Acknowledgments

Built with ❤️ by Neural Forge Labs for Indonesian businesses.

Special thanks to:

• Go community — pgx, chi, golang-migrate
• Next.js team — App Router, Turbopack
• Recharts — beautiful, composable charts
• Indonesian UMKM — inspiration for localization

---

If you find StockKit useful, please ⭐ star the repository!

⬆ Back to top