Tijarah Smart · تجارة سمارت
A bilingual (Arabic / English) inventory and financial management system for merchants, where every transaction updates stock, landed cost, ledgers, and profit in one atomic operation.
Built with Next.js 16 (App Router), React 19, TypeScript, Prisma, and NextAuth. Arabic-first and fully right-to-left, with English as a second locale.
The problem it solves
Small and mid-size merchants usually run inventory in one tool and finances in another — often spreadsheets — so stock levels, landed costs, cash balances, and profit never reconcile. A sale is recorded in one place, the cost of what was sold in another, and the "real" profit is a guess at month-end.
Tijarah Smart removes the gap: a sale, purchase, stock movement, expense, or payment is posted once, through a single transactional service that updates inventory, account balances, cost, and profit together — and every number stays traceable to the transaction behind it. There are no disconnected pages and no placeholder dashboards.
It's built for real retail / e-commerce operations in the Arabic-speaking market, including Salla and 3PL (Fast Hub / Omniful) integration.
Key features
- Unified posting engine — sales, purchases, stock moves, expenses, and payments each post as a single atomic transaction that updates inventory, ledgers, cost, and profit, with an audit log. The UI never mutates balances directly; it calls a service that owns the transaction.
- Inventory & warehouses — multi-warehouse receive, issue, transfer (with in-transit receiving), stock counts with a review step, manual adjustments, and full movement history.
- Purchasing & sales — purchases recorded at real landed cost; sales with returns; live customer and supplier balances.
- Finance — chart of accounts, payments, a transactions ledger, expense tracking, and reconciliation.
- Live reporting — dashboard, gross/net profit, inventory value, and cash balance, computed from the ledger rather than stored snapshots.
- Fully bilingual — Arabic (RTL, default) and English (LTR); every user-facing string comes from message catalogs (
messages/ar.json, messages/en.json).
- Role-based access — owner / staff / viewer roles, with authorization re-read from the database on every mutation (the session token is a cache, never the authority).
- External integrations — Salla (Saudi e-commerce) OAuth and Fast Hub / Omniful 3PL, with third-party credentials encrypted at rest (key derived from
AUTH_SECRET).
- Exact money math — money as integer minor units, quantities as integer thousandths, unit costs scaled ×10,000. No floating-point money, ever.
Architecture
A modular monolith: a Next.js App Router front end over a set of server-side services, with one transactional posting engine as the single writer of financial state.
flowchart TD
subgraph Client["Browser — Next.js App Router (AR / RTL · EN)"]
UI["React 19 Server + Client Components<br/>next-intl i18n"]
end
subgraph Server["Next.js server"]
SA["Server Actions / Route Handlers<br/>Zod validation"]
AUTH["NextAuth v5<br/>membership re-checked per mutation"]
SVC["Posting engine — src/services/<br/>one atomic transaction + audit log"]
CRYPTO["src/lib/crypto.ts<br/>encrypts stored credentials"]
end
DB[("Prisma 7<br/>SQLite · PostgreSQL-portable")]
SALLA["Salla OAuth API"]
FASTHUB["Fast Hub / Omniful 3PL"]
UI -->|request| SA
SA --> AUTH
SA --> SVC
SVC -->|"inventory · ledgers · cost · profit<br/>(single transaction)"| DB
SVC --> CRYPTO
CRYPTO --> DB
SVC <-->|sync orders / costs| SALLA
SVC <-->|fulfilment| FASTHUB
Design decisions that matter (see docs/decisions.md):
- Cost and profit are gated at construction time, not hidden in the client — a value computed into a client component's props ships in the RSC payload whether or not it's rendered, so it must never be built unless the viewer is allowed to see it.
- The schema stays PostgreSQL-portable; SQLite is a development convenience, not a design constraint.
- Reporting excludes cancelled orders before trusting payment status, so revenue and receivables can't be overstated.
Tech stack
| Layer | Technology |
|---|
| Framework | Next.js 16 (App Router), React 19 |
| Language | TypeScript |
| Styling | Tailwind CSS 4 |
| Data | Prisma 7 + better-sqlite3 (PostgreSQL-portable schema) |
| Auth | NextAuth v5 |
| i18n | next-intl (Arabic RTL + English) |
| Validation | Zod |
| Exports | ExcelJS |
| Tests | Vitest + Testing Library |
| Deploy | Caddy (auto-TLS) + systemd |
Getting started
npm install
cp .env.example .env # then set AUTH_SECRET: openssl rand -base64 48
npm run db:push # apply the Prisma schema to the database
npm run seed # build a demo company (safe to re-run)
npm run dev
The app runs at http://localhost:3000, with locales /ar (default, RTL) and /en.
The seed creates a demo company. Default owner login: [email protected] / demo12345 (other roles are in prisma/seed.ts).
Commands
| Command | What it does |
|---|
npm run dev | Development server |
npm run build | Production build |
npm test | Full test suite (Vitest) |
npm run lint | ESLint |
npm run db:push | Apply prisma/schema.prisma to the database |
npm run seed | Rebuild the demo company |
Screenshots
Add screenshots here.
| |
|---|
| Dashboard (occupancy of cash, stock, profit) | docs/screenshots/dashboard.png |
| New sale (bilingual, RTL) | docs/screenshots/sale.png |
| Inventory / warehouses | docs/screenshots/inventory.png |
| Profit & finance | docs/screenshots/profit.png |
What I learned / next steps
What this project taught me
- Designing a single source of truth for money, where correctness (no float drift, no double counting, every figure traceable) matters more than convenience.
- Guarding server-computed values — cost, margin — from leaking into the client through the React Server Components payload.
- Building a product that is bilingual and bidirectional from the data layer up, not bolted on at the view.
- Modeling real commerce operations: landed cost, multi-warehouse transfers with in-transit stock, returns, and 3PL reconciliation.
Roadmap (Stage 1 — the core merchant loop — is complete; later stages are planned)
- Deeper warehouse operations and finance reporting.
- AI-assisted invoice/expense capture that reads a receipt and posts the expense automatically.
- PostgreSQL production deployment.
- Expanded Salla / Fast Hub synchronisation.
Status: Stage 1 (register → company setup → products → receive/sell/transfer/count → expenses/payments → accurate profit, cash, and customer/supplier balances) is complete and covered by the test suite.
License
Released under the MIT License.
