1. The Need: From Flat Names to Canonical <TYPE>
Historically, Tally commands were exposed through disparate, ad-hoc naming patterns like stockItems, uom, ledgers, and groups. This created impedance mismatch with Tally's native TDL, where every master object adheres to a strictly defined XML attribute: <TYPE>Unit</TYPE>, <TYPE>StockItem</TYPE>, <TYPE>Ledger</TYPE>, etc.
Furthermore, real-world business needs demand granular variations: querying basic names only, querying base units, or querying multi-godown batch allocations with opening balances and valuations.
| Master Entity | Old Flat Command | New Canonical <TYPE> Hierarchy | Sub-Variant Capabilities |
|---|---|---|---|
| Stock Item | stockItems | StockItem | all, names, withBaseUnits, withBatches |
| Unit of Measure | uom | Unit | all, names |
| Accounting Ledger | ledgers | Ledger | all, names |
| Stock Group | stockGroups | StockGroup | all, names |
2. The 5-Tier Ecosystem Architecture
The entire pipeline operates as a unified, decoupled distributed machine:
Organized under tdlMessage.json with canonical master keys. Returns callable functions with attached sub-variants like StockItem.withBatches() producing pure Tally Definition Language XML.
Executes a deterministic 5-stage transformation pipeline: asIs → cleaned → selected → renamed → normalized. Handles complex nested arrays and objects such as batchAllocations with Godowns, Balances, Rates, and Values.
Connects outbound via WebSocket to the Cloud Server. Contains a modular command dispatcher in ws/v2/commands/masters/ that accepts dot-notation commands (StockItem.withBatches), pulls XML from Tally Prime, transforms via tally-to-json, and transmits the clean JSON payload back.
The central cloud switchboard. Preserves legacy v1 untouched while providing v2 with Context Forwarding (query params & body) and a 30-Second Timeout Safety mechanism preventing hanging HTTP connections.
Folder depth strictly mirrors backend master hierarchy: public/masters/StockItem/withBatches/. Directly invokes /ws/StockItem.withBatches?company=..., displaying real-time batch allocation tables, search filters, and KPI metric cards.
3. Cloud Server Core Enhancements
In tally-cloud-server/routes/v2/dispatchCommand.js, two foundational architectural guidelines are enforced:
Guideline B: Context Forwarding
All query parameters (e.g. ?company=mani9) and request bodies are packaged into the WebSocket message:
{ command, query: req.query, body: req.body }. The local server receives complete context for every execution.
Guideline C: 30-Second Safety Timeout
Every pending HTTP-to-WS request tracks a timeoutId. If the local server or Tally fails to respond within 30 seconds, it cancels cleanly and returns an HTTP 504 Gateway Timeout instead of leaving browser connections hanging.
4. Frontend Deep Folder Hierarchy
Because each Tally master type and sub-variant presents distinct dimensions (e.g. Batches contain Godowns and Expiry; Base Units contain UOM codes), each view is housed in its own dedicated directory tree:
tally-cloud-server/
└── public/
├── index.html # Central Gateway & Directory Dashboard
├── docs/
│ └── index.html # Full Architecture Story Documentation
└── masters/
├── StockItem/
│ ├── withBatches/ # Deep Variant View for Batch Allocations
│ │ ├── index.html
│ │ ├── index.css
│ │ └── index.js
│ ├── withBaseUnits/ # (Ready for sibling variant)
│ └── all/
├── Unit/
│ └── all/
└── Ledger/
└── all/
5. Parameter Naming Convention: in and local
All JavaScript functions strictly adhere to the project's explicit input traceability pattern:
// 1. Functions accept a single configuration object with 'in'-prefixed keys export function fetchStockItemsWithBatches({ inCompany, inFilterOptions }) { // 2. Immediately map 'in' parameters to 'local' variables at the top const localCompany = inCompany; const localFilterOptions = inFilterOptions; // 3. Exclusively use 'local' variables throughout the function body const url = `/ws/StockItem.withBatches?company=${encodeURIComponent(localCompany)}`; return fetch(url); }
6. Interactive API Sandbox
Test the live cloud server endpoints directly from this documentation page:
// Select an endpoint above to run a live test...