v1.0.0 FlowForge

📡 FlowForge — ISP Town Manager v1.0.0

Initial public release · Offline-first ISP management platform — hierarchical area/town structure, subscriber profiles, LIFO billing logic, Excel import/export, bulk billing, and full financial ledger. Zero backend required.

🌐 Live: flowforgeisp.vercel.app

---

1 · Highlights

Attribute	Value
Frontend	React 19 · TypeScript 99% · Vite · Tailwind CSS
Data handling	SheetJS (xlsx) — Excel import & export
Icons	Lucide React
Persistence	localStorage — no backend, no database setup
Architecture	SPA · ES Modules via importmap
Deployment	Vercel
Areas	4 color-coded (A, B, C, D)
Payment logic	LIFO — Current Bill cleared before Previous Pending
Billing	Bulk monthly bill generation per area
Import	Drag-and-drop .xlsx with smart town/member detection

---

2 · What's New

🏙️ Area & Town Management

• 4 color-coded areas (A, B, C, D) — each area groups its own towns and tracks outstanding balances independently.
• Town CRUD — Create, edit, and delete towns within specific areas. Each town card shows active subscriber count, total outstanding balance, and monthly revenue at a glance.
• Stats at a glance — per-town and per-area summaries update in real time as payments are recorded.

👥 Subscriber Management

• Detailed profiles — Name, Phone, CNIC, Package (Mbps), Address, and free-text Notes per subscriber.
• Status tracking — Active, Suspended, Disconnected with colour-coded visual badges.
• Real-time search & filter — filter subscribers by name, phone number, subscriber ID, or status instantly.
• Pagination — optimised tables handle large subscriber lists without performance degradation.

💰 LIFO Billing & Ledger

• Transaction ledger — full Debit/Credit history per subscriber in MemberLedger.tsx.
• Previous Pending vs Current Bill split — dues are displayed as two separate cards showing old debt and the current month's charge independently.
• Payment receipt modal — visual confirmation showing balance before and after every payment recording.

📥 Excel Import Wizard (ImportWizard.tsx)

• Drag-and-drop .xlsx file upload via excelParser.ts.
• Smart heuristic parsing:
  • Town headers detected by pattern: number + dot + name (e.g. 01. My Town)
  • Member rows parsed by serial number in Col A, name ± phone in Col B, package in Col C, bill amount in Col D
• Preview parsed data before committing — confirm or cancel.

📤 Excel / CSV Export (csvService.ts)

• Download full subscriber lists and financial ledger data for any specific town as .xlsx or .csv.
• Formatted output ready for external accounting software or management reporting.

📊 Executive Dashboard (DashboardView.tsx)

• Revenue tracking, daily order metrics, active subscriber utilization.
• Low-stock and inventory alerts for ISP equipment management.
• Activity logs showing the most recent actions across all areas.

🧾 Bulk Monthly Billing (BillingModal.tsx)

• One-click monthly bill generation for all Active subscribers in a selected area.
• Creates a Bill ledger entry per subscriber, increasing their Total Due and Balance for that month.

---

3 · TypeScript Interfaces (types.ts)

interface Member {
  id: string;
  name: string;
  phone: string;
  cnic: string;
  packageMbps: number;
  address: string;
  notes?: string;
  status: 'active' | 'suspended' | 'disconnected';
  totalDue: number;       // running total owed
  balance: number;        // current unpaid balance
}
 
interface Town {
  id: string;
  areaId: 'A' | 'B' | 'C' | 'D';
  name: string;
  members: Member[];
}
 
interface LedgerEntry {
  id: string;
  memberId: string;
  type: 'debit' | 'credit';
  amount: number;
  description: string;    // e.g. "BILL OF FEB" | "Payment Received"
  date: string;           // ISO date string
  previousBalance: number;
  newBalance: number;
}

---

4 · LIFO Billing Cycle — Full Walkthrough

LIFO (Last-In, First-Out) payment logic means the most recently generated bill is cleared first:

Step 1: User has 1,200 old debt (Previous Pending)
Step 2: Monthly billing runs → new 500 bill generated for February
        User now owes: 1,200 (old) + 500 (Feb) = 1,700 total
Step 3: User pays 500
Step 4: System applies 500 to the CURRENT bill (Feb)
        → Feb bill: ✅ PAID
        → Previous Pending: still 1,200 (unchanged)
Step 5: Dashboard reflects 1,200 total outstanding

Why LIFO? Psychologically, subscribers feel they have "cleared this month" even with existing old debt. This reduces immediate billing disputes while keeping overdue balances visible for follow-up.

---

5 · Storage & Data Reset

All data is persisted to localStorage via storageService.ts. The app survives page reloads but data is device-specific — not synced across devices.

To reset all data:

1. Open DevTools (F12)
2. Application tab → Local Storage → your domain
3. Right-click → Clear
4. Refresh the page

This clears all towns, subscribers, and ledger entries. There is no confirmation prompt — once cleared, data cannot be recovered.

Running locally:

git clone https://github.com/ibtesaamaslam/FlowForge.git
cd FlowForge
 
# Python
python3 -m http.server 8000
 
# OR Node
npx http-server .
 
# Open: http://localhost:8000

---

6 · Known Limitations

Limitation	Explanation
localStorage only	Data resets if browser storage is cleared; not synced across devices or users
No real-time multi-user	Two operators editing simultaneously will overwrite each other's changes on refresh
No authentication	Role selection (Admin/Operator) is not protected by a password in this release
No payment gateway	Payment recording is manual — no Easypaisa / JazzCash API integration yet
No SMS notifications	Subscriber reminder toggle records preference but sends no actual SMS
Single-device only	No cloud backup; if the device's storage is cleared, all data is lost

---

7 · License

Distributed under the MIT License — free to use, modify, and distribute.

---

8 · Author

Ibtesaam Aslam · @ibtesaamaslam

---

⭐ If FlowForge helped streamline your ISP operations, please consider giving it a star!

🌐 [flowforgeisp.vercel.app] · Built with ❤️ by Ibtesaam Aslam