App Guide

Architecture · modules · workflows — the canonical user manual for AlmondsIndia

Your guided tour of AlmondsIndia.com

Explore every module, see who uses what, and walk through the full buyer / vendor / admin journeys. Stuck? Open the chat bubble on the right — it's wired to the same knowledge base you're reading here.

7 architecture layers 23 modules 6 personas 3 role journeys

Technology stack

  • ● Next.js 14.2 App Router
  • ● React 18 + TypeScript 5.5
  • ● Tailwind CSS 3.4 + Lucide icons
  • ● Recharts (charts)
  • ● useSyncExternalStore (Zustand-style external store)
  • ● 100% mock data — no backend, no DB

Application layers

Routing layer (app/)
Next.js App Router with three top-level groups: app/(app)/* for the authenticated workspace (sidebar + topbar shell), app/mobile/* for the React Native preview, and app/login + app/page.tsx for the public surfaces.
Data layer (lib/mock.ts)
Seed data for every entity — vendors, factories, listings, batches, warehouses, orders, RFQs, returns, payments, loans, growers, imports, carriers, posts, support tickets. ~2,300 lines.
State / mutations (lib/store.ts)
External-store pattern via useSyncExternalStore. Every write goes through a typed action (buyerActions, vendorActions, adminActions, returnActions, financeActions, etc.) that updates state and notifies subscribers. Audit log + notification side-effects are co-located with the mutations.
Portal stores (lib/buyer-store.tsx, lib/vendor-store.tsx)
Sub-portal sessions — buyer cart, current persona, helper memos. Delegate all platform mutations to lib/store.ts.
i18n (lib/i18n.tsx)
Lightweight provider with 5 language dictionaries (EN, HI, MR, GU, KS). t(key) falls back to English for any missing key.
Role / RBAC (lib/role.tsx)
Persona context + NAV_BY_ROLE whitelist driving sidebar visibility per role.
UI components (components/*)
Reusable primitives — Sidebar, Topbar, NotificationBell, ChatThread, ReviewForm, ReturnForm, PodUpload, DispatchWizard, QualityStandardsPanel, CommodityRoadmap, DemoFillButton, GuideChatbot.

High-level data flow

               ┌──────────────────────────────────────────────┐
               │              app/(app)/* pages               │
               │   (Sidebar + Topbar shell · role-scoped)     │
               └──────┬────────────────────────────────┬──────┘
                      │ useSyncExternalStore           │
                      ▼                                ▼
        ┌───────────────────────┐         ┌─────────────────────────┐
        │      lib/store.ts     │◄────────│  lib/buyer-store.tsx    │
        │  (mutations · audit · │         │  lib/vendor-store.tsx   │
        │   notifications)      │         │  (portal sessions)      │
        └──────────┬────────────┘         └─────────────────────────┘
                   │ reads
                   ▼
        ┌───────────────────────┐         ┌─────────────────────────┐
        │       lib/mock.ts     │         │      lib/i18n.tsx       │
        │   (seed entities)     │         │    (5 dictionaries)     │
        └───────────────────────┘         └─────────────────────────┘
                   │
                   ▼
        ┌───────────────────────┐
        │  components/*  (Chat, │
        │  ReturnForm, PodUpload,
        │  DispatchWizard …)    │
        └───────────────────────┘

Single source of truth

Both this guide and the right-side chatbot read from lib/guide-knowledge.ts. Adding a new module there updates both surfaces automatically — no duplicate documentation to maintain.