How to set up and use BPS CA

System Architecture & Core Concepts

BPS CA is a hosted multi-tenant ERP operating layer for company analysis, ledger management, and accountant collaboration. Production compute and primary data stores run on Oracle Cloud Infrastructure (ap-hyderabad-1). Each company is a tenant-scoped workspace backed by PostgreSQL tables with a company_id boundary, so catalog, user, transaction, document, and forecast reads stay inside the active company.

Invoice files are stored through the application's tenant-isolated object-storage proxy (MinIO on the same primary stack). The OCR pipeline validates file signatures, creates a tenant-scoped job, extracts a draft, and leaves final approval to an authorized Admin. Confirmed dated transaction history then feeds stock projections and forecasting.

Security & trust

Tenant isolation, role-based access, and India-region residency are summarized on the public Security page. The CSA STAR badge in the site footer links to our live CSA STAR Registry listing (Level One self-assessment).

Super Admin Operations & Platform Controls

Super Admins operate at the platform level. The Master Tenant Ledger shows registered company names, GST identifiers, billing plans, subscription states, and available Admin or Accountant contacts without loading tenant inventory or bill data.

A pending tenant can be reviewed for a controlled Enterprise activation override. Platform health and PM2 process telemetry are infrastructure concerns and remain separate from tenant business records; the dashboard provides a monitoring reference rather than embedding live process counters.

What are the roles in BPS CA?

• Super Admin: Platform management and tenant oversight.
• Admin: Company owner or operator with full ledger, catalog, inventory, approval, and staff controls.
• Accountant: Restricted bill-processing access granted through a secure pairing code.

Integrations & Cloud Sync

BPS CA connects desktop and cloud accounting ledgers into one tenant-scoped Tower. Connection setup, revocation, sync schedules, and API keys are Admin-only. Accountants use the Tally bridge status view and document upload — they cannot disconnect ledgers or change sync cadence.

Cloud ledgers (Zoho Books, Xero, QuickBooks Online)

1. Connect (Admin): Open /admin/integrations, choose a provider, and complete the OAuth handshake in a new tab. Tokens are stored encrypted and refresh when the provider allows it. Xero uses granular invoice and contact read scopes so BPS only requests the data it syncs.
2. Sync Now / Sync all: Pull bills and invoices into the universal ingest shape. Counts shown after sync are real accepted / rejected / unmapped totals — never invented placeholders. Replay-safe ledger IDs prevent duplicate pending trades from the same document.
3. Scheduled sync (opt-in): Admins may enable a cadence on Integrations. Background ticks run only when an ops host secret is configured and the company schedule is enabled. Default is off (no silent cron).
4. Alias remediation: Unmapped product, party, or location labels deep-link to Catalog, Partners, or Inventory so you attach aliases to existing masters — nothing is auto-created.

Desktop ledger (Tally Prime)

1. Windows Sync Agent: Accountants download bps-tally-agent.exe from /accountant/bridge. Admins mint the API key (shown once); the agent probes Tally on the local XML/ODBC port (commonly 9000) and heartbeats into BPS.
2. Accountant bridge: Status polls about every five seconds and shows connection state plus the explicit Managed by Admin — Disconnection restricted notice — no Disconnect, Revoke, or Schedule controls for Accountants.

Governance & RBAC

• Admin: OAuth connect/disconnect, agent API keys, Sync Now / Sync all, opt-in schedules, and alias remediation.
• Accountant: Bridge download + status + document upload only. Middleware blocks /admin/integrations and related Admin mutation paths.
• Client portal: Statement access only — not used for ledger bridge setup.

Admin Role: Complete Operational Manual

1. Analytics dashboard

   Open Analytics after the team has confirmed transactions. Work through each node in this order:

   • Analytics KPI summary: Start with confirmed-trade totals and trends. The figures originate from confirmed outward and sample transactions, so unfinished Accountant uploads cannot distort the summary.
   • Sales history chart: Inspect the time-ordered confirmed-sales series to understand movement across the reporting window. The chart uses dated transaction events rather than an undated snapshot total.
   • Top products volume: Use the product ranking to identify high-volume SKUs. Data comes from confirmed transaction lines joined to the company catalog, with quantity and revenue calculated from the tenant ledger.
   • Top buyers volume: Use buyer rankings to prioritize customer follow-up. The rows originate from confirmed client-linked outward and sample trades in the current company.
   • Next-order forecast: Review expected buyer-product timing from dated confirmed order history. Frequency, average quantity, and order gaps require sufficient historical transactions.

2. Asymmetric reconciliation & pricing anomalies

   Approvals keep Inward, Outward, and Sample on separate tabs. Inward purchases compare ledger/book fields, morning OCR extracts, and evening gate-pass proof. Outward sales and samples confirm on books + evening dispatch (morning OCR optional when the ledger already created the row). Ingest-source badges show upload vs cloud vs Tally agent. Inward queues flag buy-price anomalies against recent purchase history so you investigate spikes before confirming. Voided cloud invoices stay out of live totals.

3. Catalog search, creation, and metadata

   Use the Products, Clients, and Vendors views to find the company-scoped records used by bill processing. Add new SKUs or parties from the protected creation controls and maintain aliases for OCR and cloud label matching. Multi-line Universal Tax / VAT / GST lines arrive on trades through edge ingest into tax_breakdown — catalog metadata stays focused on SKUs, parties, and procurement fields.

4. Inventory, transfers & procurement cues

   Read on-hand stock by warehouse, transfer within live source balances, and act on days-of-cover / ADU reorder signals from dated outward history. Map unmapped cloud locations with warehouse aliases — BPS never invents warehouses from sync noise.

5. Staff pairing and revocation

   Generate a time-limited pairing code for an Accountant, review pending requests, and manage the staff list. Deactivating an Accountant immediately blocks future authentication while retaining historical records.

6. Integrations (cloud and Tally)

   Connect Zoho, Xero, or QBO with OAuth (new-tab Connect), run Sync Now, and remediate unmapped names via aliases. Issue Tally agent API keys on Bridge and keep schedules opt-in. See Integrations & Cloud Sync above for the full bridge tutorial.

Accountant Role: Bill Processing & Dispatch Manual

1. Secure device pairing at /pair

   Open the clean /pair URL, enter the code supplied by the company Admin, and submit the request. The server ties the request to the intended company and expires unused pairing codes.

2. Identity verification

   Complete a lightweight staff profile when prompted (name, address, phone, family contact fields). BPS CA does not collect national government ID numbers. After onboarding, use Bridge and Document upload from the Accountant menu.

3. Windows Tally Sync Agent

   Download the Windows .exe from Bridge, place .env.local beside it with the Admin-issued API_KEY, keep Tally XML listening, and leave the agent running. Bridge status becomes Active & Synced after a good heartbeat. You cannot mint or revoke keys — Managed by Admin.

4. Morning bill intake & OCR staging

   Prefer vendor purchase invoices in morning intake for the full inward three-way path. Wait for optical extraction, then Verify extracted fields before saving a pending trade. Sales and sample rows often already exist from ledger sync — attach evening gate-pass / dispatch proof for Admin confirm. Do not swap morning and evening slots.

5. Pending handoff

   Saving a draft creates a pending trade locked against duplicates. The Admin confirms in Approvals; only that confirmation updates live stock and analytics history.

Comprehensive Frequently Asked Questions (FAQ)