1 System Architecture
Tadbeer Accounts is built upon a modern, highly responsive technology stack designed for reliability and performance. The frontend leverages Next.js using the App Router architecture, intertwined with React and TypeScript to ensure type safety and predictable component rendering. Vite serves as the underlying bundler for exceptional speed during development and optimized builds for production. The persistent data layer is powered by Supabase PostgreSQL, providing a robust relational database capable of handling complex financial queries and strict transactional integrity.
The core business logic is modularized into dedicated libraries. For instance, lib/accounting.ts forms the mathematical backbone of the application, meticulously handling the core double-entry mathematical balancing and ensuring no transaction is committed unless total debits perfectly match total credits. Similarly, lib/exchange.ts handles dynamic currency conversions, interfacing with exchange rate tables to calculate accurate base currency equivalents for multi-currency transactions.
The application is neatly organized into intuitive page routes. The /dashboard provides a high-level overview of financial health. The /masters route manages the foundational chart of accounts. The /vouchers route and its sub-routes accommodate the data entry of diverse financial transactions. Other dedicated routes include /invoices for billing, /items for inventory and services, an expansive /reports module containing nine distinct sub-reports for detailed financial analysis, and a /settings area for global configuration.
2 How Double-Entry Works (for non-accountants)
The fundamental principle of double-entry bookkeeping is that every financial transaction inherently affects two different accounts simultaneously. Think of it as a law of financial physics: every action has an equal and opposite reaction. In accounting terminology, one account is Debited (meaning value flows into it), while another account is Credited (meaning value flows out of it). For the financial records to remain accurate and trustworthy, the total amount of debits in the entire system must always perfectly equal the total amount of credits. This equilibrium is what accountants mean when they say the books are "balanced."
Tadbeer Accounts is deliberately engineered to abstract this complexity away from the everyday operator. Instead of forcing users to memorize esoteric debit and credit rules, the system uses plain-English form labels. Operators simply describe what occurred in everyday business terms. For example, if you pay an electricity bill, you tell the system you paid a specific expense out of your primary bank account. Under the hood, Tadbeer Accounts automatically translates this plain-English action into the correct accounting entry: it seamlessly debits the Electricity Expense account and credits the Bank account, ensuring mathematical harmony without requiring the user to possess a formal accounting degree.
3 Chart of Accounts / Masters
The Chart of Accounts, accessed via the /masters route, represents the foundational skeleton of your financial system. It employs a strict hierarchical structure consisting of three distinct tiers: Nature, Group, and Ledger. At the very top is the "Nature" tier, which is immutably fixed to five universal accounting classifications: Assets, Liabilities, Equity, Income, and Expenses. Below this, users can create "Groups," which act as customizable folders to organize related accounts logically. The lowest and most granular tier is the "Ledger," representing the individual, actionable accounts where actual transactions are recorded.
A practical example of this hierarchy in action would be tracking funds in a specific bank. The Nature would be "Assets." Within Assets, you might create a Group named "Current Assets." Within Current Assets, you would create the specific Ledger, such as "Bank Muscat OMR Account." When adding a new Group, the system only requires a descriptive name and the selection of its parent (either a Nature or another Group). When creating a Ledger, the user utilizes the LedgerFormModal.tsx component to specify the ledger name, assign it to a parent Group, provide an opening balance if applicable, and designate its inherent type as either a Debit (Dr) or Credit (Cr) balance account.
To preserve absolute data integrity, the system enforces strict deletion rules. You are entirely restricted from deleting any Group that currently contains child groups or ledgers. More critically, you cannot delete a Ledger if it has any posted transactions associated with it. This restriction prevents the accidental or malicious corruption of historical financial data, ensuring that the ledger history remains auditable, complete, and unalterable over time.
4 The 7 Voucher Types
Vouchers are the primary instruments for recording financial events. They are processed via the /api/vouchers Supabase route, which handles the complex orchestration of writing paired journal lines to the engine while guaranteeing transactional safety.
Purchase Voucher
The Purchase voucher is utilized whenever the business acquires goods, services, or equipment from external vendors or suppliers. In the intuitive form interface, the user selects precisely what was purchased—which links directly to an appropriate expense or asset ledger—and indicates how the purchase was funded. Funding can be marked as an immediate payment via a bank or cash account, or it can be recorded as a payable owed to a specific supplier ledger. Upon saving, the accounting engine automatically debits the chosen expense or asset account to reflect the incoming value, and credits the selected payment source or supplier payable account.
Sale Voucher
The Sale voucher is the mechanism for recording revenue when billing a client for products sold or services rendered. The operator utilizes the form to select the specific income category associated with the sale and indicates where the corresponding payment will reside. This could be an immediate deposit into a bank or cash account, or the creation of an accounts receivable ledger indicating the customer owes the business money. The engine seamlessly translates this by automatically debiting the receipt source (increasing assets) and crediting the designated income account (increasing revenue).
Receipt Voucher
The Receipt voucher is exclusively designed for recording the influx of funds into the business that are not direct, immediate sales. Its primary use case is collecting payments from customers who previously owed money (thereby settling an outstanding Accounts Receivable balance) or recording the infusion of new capital investment by owners. The user specifies the amount and the source. The system executes this by debiting the destination bank or cash account (showing the increase in liquid assets) and crediting the source account, such as the customer's receivable ledger or the owner's capital ledger.
Payment Voucher
The Payment voucher functions as the mirror image of the Receipt voucher. It is used exclusively when funds are exiting the business. This typically involves remitting payment to a supplier for a previously recorded payable, or paying for an immediate expense directly out of cash reserves without raising a formal purchase order. The system accurately reflects this outflow by debiting the specific payable or expense account (reducing the liability or recognizing the expense) and crediting the designated bank or cash account (reducing the liquid asset balance).
Journal Voucher
The Journal voucher is the master tool for accountants, providing a fully open, unrestricted interface for complex or specialized entries. It is typically reserved for manual adjustments such as recording asset depreciation, writing off bad debt, rectifying previous entry errors, or executing complex multi-line inter-account transfers. The operator has complete freedom to select any combination of debit and credit ledgers, provided the fundamental rule is met: the total debits inputted must mathematically equal the total credits before the system allows the voucher to be posted.
Purchase Return
The Purchase Return voucher acts as a specialized reversal mechanism for previous purchases. It is employed when the business needs to return defective or unwanted goods back to a supplier, or when negotiating a refund or discount after a purchase has already been formalized. By entering the details, the system intelligently creates the inverse journal entries of a standard purchase, effectively reducing the previously recorded expense or asset balance and correspondingly reducing the liability owed to the supplier or increasing the expected refund.
Sales Return
The Sales Return voucher is utilized to gracefully reverse a previously recorded sale. This is necessary when a customer returns purchased goods, requests a refund for services, or when the business needs to issue a formal credit note against an existing invoice. The system processes this by reversing the original sales logic: it reduces the recorded income and subsequently decreases the outstanding accounts receivable balance associated with that specific customer, ensuring the financial statements accurately reflect the adjusted reality.
5 Multi-Currency & Exchange Rates
Tadbeer Accounts is fully equipped to handle international commerce through its robust multi-currency functionality, managed primarily in the /settings/exchange-rates module. Businesses can define a primary base currency, while effortlessly recording transactions in various foreign denominations. When a user creates a transaction in a non-base currency, the system immediately requires an exchange rate to translate the value.
Users have the capability to add highly specific, custom exchange rates tailored to particular dates, ensuring historical accuracy for transactions executed under fluctuating market conditions. In the absence of a date-specific custom rate, the system intelligently defaults to fallback static rates defined in the settings. Upon saving any multi-currency voucher, the core accounting engine intercepts the data, applies the appropriate rate to calculate the exact base currency equivalent, and records both the foreign amount and the localized base amount in the underlying ledger tables for seamless, unified reporting.
6 Invoices
The invoicing module, accessible via /invoices and the creation interface at /invoices/new, provides a comprehensive billing solution. Users can construct detailed invoices by adding specific line items, adjusting quantities, and defining unit prices. The system handles complex VAT calculations automatically, appending the appropriate tax amounts based on configured item settings to generate the final total.
Once finalized, invoices are elegantly formatted for physical distribution or digital sharing using the PrintableInvoice.tsx component, which ensures a highly professional, branded appearance. Crucially, the invoice system is tightly integrated with the core ledger. When a customer remits payment for an invoice, that specific payment is logged via a Receipt voucher and explicitly linked back to the originating invoice, allowing operators to track exactly which bills have been settled and which remain outstanding.
7 Items / Inventory
The /items module acts as the centralized catalog for all products and services offered by the business. It allows for the detailed tracking of standard inventory units, service charges, or digital products. The data entered here populates the selectable dropdowns within the invoicing interface, drastically speeding up the billing process and ensuring consistency in naming and pricing.
Management of this catalog is streamlined through the ItemFormModal.tsx component. This modal allows operators to swiftly add new items, define standard selling prices, apply necessary tax codes, and link specific items to designated income ledgers. This linkage ensures that when an item is selected on an invoice, the resulting revenue is automatically routed to the correct financial bucket in the general ledger without manual intervention.
8 9 Financial Reports
The reporting suite translates raw ledger data into actionable business intelligence. Each report serves a distinct analytical purpose, empowering management to make informed financial decisions.
Trial Balance
A master summary listing the closing balances of every active ledger account in the system at a specific point in time. It proves the fundamental mathematical accuracy of the books, ensuring total debits equal total credits before preparing formal financial statements.
Profit & Loss
The ultimate performance indicator, detailing the company's revenues minus its expenses over a specified period. It provides management with a clear, unequivocal bottom-line number determining whether the business generated a net profit or suffered a net loss.
Balance Sheet
A snapshot of the company's financial health at an exact moment. It details what the business owns (Assets), what it owes to others (Liabilities), and the residual value belonging to the owners (Equity), proving the accounting equation: Assets = Liabilities + Equity.
Ledger Report
A microscopic view of a single, specific account. It lists every individual transaction that affected that ledger chronologically, providing an exhaustive audit trail to investigate discrepancies or verify the history of a specific customer, supplier, or expense category.
VAT Report
A specialized compliance report isolating all transactions involving Value Added Tax. It calculates the total VAT collected on sales versus the total VAT paid on purchases, yielding the exact net amount owed to or refundable by the tax authority.
Sales Register
A chronological log of all revenue-generating transactions. Management uses this to analyze sales volume trends, identify peak billing periods, and review the total value of goods or services provided to clients over a given timeframe.
Purchase Register
A detailed chronological record of all outgoing expenditures and supplier acquisitions. This is crucial for analyzing spending habits, monitoring procurement costs, and reviewing total liabilities incurred from various vendors.
Receipts Report
A focused analysis of pure cash inflow. It tracks every instance where money physically entered the business bank or cash accounts, essential for monitoring cash flow positivity and verifying customer payment collections.
Payments Report
The counterpart to receipts, tracking pure cash outflow. It details every check written, transfer made, or cash distributed, allowing management to tightly monitor liquidity and ensure funds are not being depleted unnecessarily.
9 Settings
The /settings interface acts as the global control panel for the Tadbeer Accounts application. Here, administrators define the core parameters that govern the behavior of the entire system. Key configurations include establishing the comprehensive company profile—which dictates the branding and contact information dynamically rendered on outgoing invoices—and setting the foundational baseline currency that anchors all financial reporting.
Furthermore, administrators establish the critical financial year start date, ensuring that reports like the Profit & Loss statement correctly aggregate data across the appropriate fiscal calendar rather than a standard calendar year. The settings module also houses powerful data management utilities, notably the /settings/import function. This utility allows for the bulk ingestion of external financial data via structured files, facilitating smooth migrations from legacy accounting software and rapidly accelerating the initial onboarding process.