A full-stack, three-tier business management and distribution tracking platform built for field workers and central administrators. The system combines an offline-first mobile app, a web-based admin dashboard, and a synchronized REST API backend.
┌─────────────────────────────────────────────────────────┐
│ Liverat Business System │
├──────────────┬──────────────────────┬───────────────────┤
│ Mobile App │ Admin Web Panel │ Backend API │
│ (Expo RN) │ (Next.js) │ (FastAPI) │
│ Reactjs │ Port: 3000 │ Port: 8000 │
└──────┬───────┴──────────┬───────────┴────────┬──────────┘
│ │ │
└──────────────────┴──── SQLite DB ─────┘
Designed for Android field workers in areas with unstable internet.
- Dual Role System:
- 🧾 Order Takers — Record shop orders (Carton / Piece quantities)
- 💼 Salesmen — Record cash received vs. credit given per shop
- Offline SQLite Database — Caches shops, products, and pricing locally
- Background Auto-Sync — Syncs pending data to the server on reconnection
- Smart Unit Handling — Supports Carton and Piece transactions dynamically
- Session Persistence — Login sessions survive app restarts via AsyncStorage
A full-featured dashboard for the administration team.
| Module | Description |
|---|---|
| Dashboard | Summary stats and live activity overview |
| Users | Create & manage staff accounts with role assignment |
| Shops | Manage customer/shop distribution network |
| Items | Product catalog with dual-pricing (Carton & Box) |
| Companies | Manage supplier/company records |
| Agencies | Vendor purchase invoices & agency management |
| Stock | Independent inventory with carton/box quantity tracking |
| Orders | Live order logs from field Order Takers |
| Sales | Salesman dispatch & revenue realization records |
| Manual Orders | Manually enter orders from admin panel |
| Manual Sales | Manually enter sales records from admin panel |
| Reports | Print-ready dispatch & revenue reports (branded "Liverat Report") |
Secure, synchronization-capable API powering both clients.
| Route | Purpose |
|---|---|
/api/v1/auth |
JWT-based login & token management |
/api/v1/users |
User CRUD & role management |
/api/v1/shops |
Shop/customer management |
/api/v1/items |
Product & pricing catalog |
/api/v1/companies |
Company/supplier management |
/api/v1/agencies |
Agency & vendor invoice management |
/api/v1/stocks |
Stock inventory management |
/api/v1/orders |
Order creation, listing & sync |
/api/v1/sales |
Sales records & sync |
/api/v1/sync |
Mobile bootstrap data sync endpoint |
/api/v1/reports |
Report summary data |
/api/v1/price-types |
Price type configuration |
| Tier | Technology | Version |
|---|---|---|
| Mobile App | React Native + Expo | SDK 54 |
| Mobile DB | expo-sqlite | ~16.0 |
| Mobile State | AsyncStorage | 2.1.2 |
| Navigation | React Navigation | v7 |
| Admin Panel | Next.js | 14+ |
| Admin Styling | TailwindCSS | Latest |
| Backend | Python + FastAPI | ≥0.111 |
| ORM | SQLAlchemy | ≥2.0 |
| Database | SQLite | (via SQLAlchemy) |
| Auth | JWT (python-jose + bcrypt) | — |
| Migrations | Alembic | ≥1.13 |
| Server | Uvicorn | ≥0.30 |
- Python 3.10+
- Node.js 18+
- Expo Go app on Android device (or Android Emulator)
cd backend
# Create and activate virtual environment
python -m venv venv
.\venv\Scripts\Activate.ps1
# Install dependencies
pip install -r requirements.txt
# Start the server
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000✅ API available at:
http://localhost:8000📄 Interactive Docs:http://localhost:8000/docs
Default Admin Credentials (auto-created on first start):
- Username:
admin - Password:
**********
cd admin-panel
npm install
npm run dev✅ Dashboard available at:
http://localhost:3000
Step 1 — Find your PC's local IP address:
ipconfig | findstr "IPv4"Step 2 — Update app.json with your actual IP:
"extra": {
"apiBase": "http://<YOUR_PC_IP>:8000/api/v1"
}Step 3 — Start Expo:
# From the root directory (e:\business-app)
npx expo start -c📱 Scan the QR code with Expo Go on Android (both devices must be on the same Wi-Fi)
Run this in PowerShell as Administrator to allow mobile connections to your backend:
netsh advfirewall firewall add rule name="Allow Port 8000" dir=in action=allow protocol=TCP localport=8000business-app/
├── app.json # Expo config (set apiBase IP here)
├── package.json # Root Expo dependencies
├── index.js # Expo entry point
│
├── mobile-app/ # React Native mobile app
│ ├── App.js # Root component & screen router
│ ├── Root.js # Session persistence wrapper
│ ├── config/
│ │ └── api.js # API base URL config (reads from app.json)
│ ├── screens/
│ │ ├── HomeScreen.js # Role selection screen
│ │ ├── OrderTakerLogin.js
│ │ ├── OrderTakerScreen.js
│ │ ├── SalesManLogin.js
│ │ └── SalesManScreen.js
│ ├── services/
│ │ ├── api.js # HTTP API calls (login, sync)
│ │ └── session.js # AsyncStorage session management
│ └── database/
│ └── database.js # Local SQLite schema & queries
│
├── admin-panel/ # Next.js admin dashboard
│ └── src/
│ ├── app/
│ │ ├── login/ # Login page
│ │ └── admin/ # Protected admin pages
│ │ ├── page.tsx # Dashboard
│ │ ├── users/
│ │ ├── shops/
│ │ ├── items/
│ │ ├── companies/
│ │ ├── agencies/
│ │ ├── stock/
│ │ ├── orders/
│ │ ├── sales/
│ │ ├── manual-orders/
│ │ ├── manual-sales/
│ │ └── reports/
│ └── lib/
│ └── api.ts # Fetch wrapper with JWT auth
│
└── backend/ # FastAPI backend
├── main.py # App entry point & startup
├── requirements.txt # Python dependencies
├── alembic.ini # Migration config
├── database.db # SQLite database file
└── app/
├── api/routes/ # API route handlers
├── models/ # SQLAlchemy ORM models
├── schemas/ # Pydantic request/response schemas
├── core/ # Config, security & JWT
├── db/ # Database session & base
└── services/ # Business logic & sync service
- JWT Authentication — All API endpoints (except
/auth/login) require a valid Bearer token - Role-Based Access Control —
admin,ordertaker, andsalesmanroles with route-level enforcement - Password Hashing — bcrypt hashing for all stored passwords
- CORS — Configurable allowed origins via
settings.BACKEND_CORS_ORIGINS - Sync Deduplication — Prevents duplicate records during network dropout/reconnect cycles
All printed reports are branded as "Liverat Report" and include:
- Orders Dispatch Summary — Printable checklist for delivery drivers
- Salesman Revenue Realization — Detailed cash inflow vs. credit ledger sheets
- Vendor Purchase Invoice — Agency-level purchase invoices
- CSV Export — One-click export for Excel / accounting software
| Issue | Cause | Fix |
|---|---|---|
No module named 'sqlalchemy' |
Wrong Python (not venv) | Run .\venv\Scripts\Activate.ps1 first |
.venv not found |
Folder is venv not .venv |
Use .\venv\Scripts\Activate.ps1 |
| Mobile app "Network Error" | Wrong IP in app.json |
Update apiBase with ipconfig output |
| Admin panel 401 errors | Not logged in | Go to localhost:3000/login and login |
| Phone can't reach backend | Windows Firewall blocking | Add firewall rule for port 8000 (see above) |
Built as a complete digital transformation pipeline for distribution network management. Developed by Muhammad Naveed — GitHub: Muhammad-Naveed342