SpecBook: 3Books - A Bespoke Accounting System

Specifications Are All You Need (SAAYN)

A Specification-Centric Model for Automated Software Synthesis via AI

Chapter 1: Chart of Accounts (Revised)

Purpose

To define the foundational data structure for the Chart of Accounts (COA) that will serve as the backbone for the 3Books accounting system. This chapter establishes the core financial accounts that all transactions will reference, ensuring the system can support the full range of standard financial reports, our bespoke Monthly Performance Report (MPR), and a wide variety of operational, audit, and customer reports as outlined in our discussions.

---

Data Model: Account

This specification outlines the data fields and constraints for the Account entity, which serves as the fundamental building block for all financial records in the system. Its structure is designed to provide the granularity needed for both simple user dashboards and detailed CPA-level reporting.

• account_id: A unique, system-generated identifier for each account. This will serve as the primary key.
• account_name: A user-defined, human-readable name of the account (e.g., "Sales Revenue," "Checking Account"). This field must be unique to prevent data ambiguity.
• account_number: An optional, user-defined number for the account (e.g., 4000, 5120). This is a common requirement for CPAs and provides a mechanism for logical grouping.
• account_type: A mandatory classification that defines the account's category from a predefined enum list. Possible values are Asset, Liability, Equity, Revenue, and Expense. This is essential for generating the Balance Sheet and P&L.
• account_subtype: A mandatory, more granular classification that provides detail within the main type (e.g., Current Asset, Cost of Goods Sold, Payroll Expenses). This is crucial for detailed reporting and for the CPA's needs.
• description: An optional field for a detailed explanation of the account's purpose.
• is_active: A boolean flag indicating if the account is currently in use. Inactive accounts are retained for historical data integrity but are hidden from the user interface for new transactions.
• created_at: A system-generated timestamp for when the account was first created.
• updated_at: A system-generated timestamp for the last modification of the account.

---

Functional Requirements

• CRUD Operations with Permissions: The system must provide an interface for users with appropriate permissions (as defined in a future User Roles chapter) to Create, Read, Update, and Delete accounts. Deletion should be a "soft delete," meaning an account is marked as inactive rather than permanently removed, to preserve historical data.
• Default COA Generation: Upon initial company setup, the system shall pre-populate a standard Chart of Accounts relevant to a small business in the United States. This default list will be fully editable to allow for customization.
• Validation Rules:
  • account_name must be a non-empty string and unique within the company's books.
  • account_type and account_subtype must be selected from a predefined, system-managed list.
  • An account with existing, associated transactions cannot be deleted. The system must prompt the user to make the account inactive instead.
• Audit Trail: All changes to an account's data (account_name, account_type, is_active, etc.) must be recorded in an audit trail (as defined in a future Audit Trail chapter) to maintain data integrity and compliance.

---

Integration Points

• Data Migration: The system must support importing a Chart of Accounts from other systems or spreadsheets (e.g., .csv or .xlsx). This functionality should include mapping tools to match imported data to our account_type and account_subtype fields.
• Transaction Feeds: The COA is the primary destination for transactions from integrated sources. Bank feeds, Stripe payments, and other integrations must use the accounts defined in this chapter to categorize transactions.

---

Chapter 2: Transactions (Revised)

Purpose

To define the foundational data model for all financial transactions within the 3Books system. This chapter establishes the core entity that records every debit and credit, linking to the Chart of Accounts. This structure is designed to support the generation of all financial reports, including the P&L, Balance Sheet, Statement of Cash Flows, and the custom Monthly Performance Report (MPR), which will now be enhanced with forecasted data from the Track3 CRM.

Data Model: Transaction

This specification outlines the data fields and constraints for the Transaction entity, which serves as the central ledger for all financial activity. It now includes fields to differentiate between booked transactions and forecasted data from the CRM.

• transaction_id: A unique, system-generated identifier for each transaction. This is the primary key.
• transaction_date: The date on which the transaction occurred or is expected to occur.
• event_month: The month and year to which the transaction belongs for the purposes of the MPR.
• description: A human-readable description of the transaction (e.g., "Payment to Alta3.com for server hosting").
• debit_account_id: A foreign key referencing the account_id from the Chart of Accounts that is debited.
• credit_account_id: A foreign key referencing the account_id from the Chart of Accounts that is credited.
• amount: The value of the transaction. This must be a positive number.
• transaction_type: An enum field to classify the origin of the transaction. Possible values include:
  • BOOKED: A finalized, auditable financial transaction.
  • TRACK3_FORECAST: A forecasted transaction originating from the Track3 CRM.
• confidence_level: A numeric value (e.g., 0-100) that indicates the probability of a TRACK3_FORECAST transaction being realized. This field is optional and only applies to forecasted transactions.
• created_at: A system-generated timestamp for when the transaction was entered into the system.
• updated_at: A system-generated timestamp for the last modification of the transaction.

Functional Requirements

• CRUD Operations with Permissions: The system must allow users with appropriate permissions to create, read, update, and delete transactions. Deleting a transaction should be a soft delete, with a record maintained in the audit trail.
• Double-Entry Validation: All BOOKED transactions must adhere to double-entry accounting principles, with a debit and a credit of equal value. TRACK3_FORECAST transactions are exempt from this requirement as they are for reporting purposes only.
• Categorization: All transactions, whether manual or imported, must be categorized by linking them to the appropriate account_ids from the COA.
• Monthly Performance Report (MPR) Logic: The system must use the event_month field to generate the MPR. The user interface for the MPR must include an option to toggle the inclusion of TRACK3_FORECAST transactions, allowing the CEO to see a standard report or a "best guess" forecast.

Integration Points

• Track3 CRM: The system will integrate with Track3's API to pull potential orders and create TRACK3_FORECAST transactions. These forecast transactions will automatically be assigned an event_month and confidence_level based on the data received from Track3. The system will perform regular, automated updates to reflect changes in the CRM.
• Bank Feeds & Payment Gateways: Transactions from integrated bank feeds and payment processors will continue to be automatically created in this table, classified as BOOKED transactions.
• Audit Trail: All creation, modification, and deletion of transactions must be logged in the audit trail. This is especially critical for BOOKED transactions to maintain a complete history for compliance and verification.

---

Chapter 3: Invoicing and Receivables

Purpose

To define the data models and workflows for managing customer information, sales, and accounts receivable. This chapter establishes the entities for Customers, Invoices, and Quotes, linking them to the core Transaction model to ensure all sales activities are accurately recorded and tracked. The system will support customizable invoicing, automated reminders, and seamless integration with our CRM (Track3) and authentication system (FIRM).

---

Data Models

Customer

This entity holds all customer-related information and links to our bespoke authentication system.

• customer_id: A unique identifier for the customer (primary key).
• firm_user_id: A foreign key linking to the user's ID in the FIRM authentication system. This ensures the customer profile is tied to a secure user account.
• company_name: The name of the customer's business.
• contact_name: The primary contact person's name.
• email: The primary email address for communication and invoicing.
• phone: The customer's primary phone number.
• billing_address: The customer's billing address.
• shipping_address: An optional shipping address.
• payment_terms: A predefined set of payment terms (e.g., "Net 30," "Due on Receipt").
• customer_group: An optional field for categorizing customers.
• created_at: Timestamp of creation.
• updated_at: Timestamp of last update.

Invoice

This entity represents a formal request for payment for goods or services rendered. It is the primary mechanism for tracking accounts receivable.

• invoice_id: A unique identifier for the invoice.
• customer_id: A foreign key linking to the Customer entity.
• invoice_number: A unique, sequential number for the invoice.
• invoice_date: The date the invoice was issued.
• due_date: The date the payment is due.
• status: An enum for tracking the invoice lifecycle (e.g., Draft, Sent, Viewed, Overdue, Paid, Partially Paid).
• total_amount: The final total of the invoice, including taxes and discounts.
• tax_amount: The total tax amount on the invoice.
• discount_amount: The total discount amount applied.
• transaction_id: A foreign key linking to a receivable Transaction entry.
• notes: An optional field for internal or customer-facing notes.
• template_id: A foreign key for the invoice template used.
• created_at: Timestamp of creation.
• updated_at: Timestamp of last update.

InvoiceLineItem

A sub-entity of an invoice that details a single item or service.

• line_item_id: Unique identifier.
• invoice_id: Foreign key linking to the parent Invoice.
• description: A description of the item or service.
• quantity: The number of units.
• unit_price: The price per unit.
• subtotal: The quantity multiplied by the unit price.
• tax_rate: The tax percentage applied to this line item.

Quote

This entity represents a proposal or estimate.

• quote_id: Unique identifier.
• customer_id: Foreign key linking to the Customer entity.
• quote_date: The date the quote was issued.
• expiry_date: The date the quote is no longer valid.
• status: An enum for tracking the quote lifecycle (e.g., Draft, Sent, Accepted, Rejected).
• total_amount: The estimated total amount.
• created_at: Timestamp of creation.
• updated_at: Timestamp of last update.

---

Functional Requirements

• Invoice/Quote Management: Allow users to create, edit, send, and track the status of invoices and quotes. The system must support the generation of quotes that can be seamlessly converted into a finalized Invoice.
• Customization: Enable the use of templates for invoices and estimates, with the ability to add and apply discounts and taxes at both the line item and invoice levels.
• Payment Matching: The system must be able to automatically match incoming payments to specific invoices, updating the Invoice status and recording a corresponding Transaction entry.
• Automated Reminders: Implement an automated system to send payment reminders for invoices that are overdue or approaching their due date.
• Job Costing: The system must track costs associated with a quote or project, a key feature for project-based billing.

---

Integration Points

• Track3 (CRM): The system must expose an API to receive quote and order data from Track3. This data will be used to automatically generate Quotes and, upon a customer's acceptance, convert them into Invoices.
• FIRM (Authentication): Customer profiles must be linked to our bespoke FIRM authentication system. This ensures a consistent user identity across both systems and supports a unified user experience.
• External API: A secure, well-documented RESTful API will be exposed to allow other systems to programmatically create and manage invoices and customers, supporting the broader ecosystem you envisioned.
• E-commerce: A future integration point will connect to e-commerce platforms to automatically generate invoices from online sales.

You're right to connect the two. This makes the system's forecasting capabilities symmetrical. It's a key requirement for the "best guess" reporting a CEO needs. I will update Chapter 4 to include this.

---

Chapter 4: Expense and Bill Management (Revised)

Purpose

To define the data models and workflows for managing expenses, vendor bills, and accounts payable. This chapter establishes the entities for Vendors, Bills, and Expenses, linking them to the core Transaction model. The system will support receipt capture, automated transaction matching, approval workflows, and now, the integration of projected expenses from the Track3 CRM to provide a more complete forecast.

---

Data Models

Vendor

This entity holds all vendor-related information, serving as the counterpart to the Customer entity.

• vendor_id: A unique identifier for the vendor (primary key).
• company_name: The name of the vendor's business.
• contact_name: The primary contact person's name.
• email: The primary email address for communication and billing.
• phone: The vendor's primary phone number.
• billing_address: The vendor's billing address.
• payment_terms: A predefined set of payment terms (e.g., "Net 30").
• created_at: Timestamp of creation.
• updated_at: Timestamp of last update.

Bill

This entity represents a formal bill received from a vendor that needs to be paid.

• bill_id: A unique identifier for the bill.
• vendor_id: A foreign key linking to the Vendor entity.
• bill_date: The date the bill was issued or is projected to be issued.
• due_date: The date the bill is due.
• status: An enum for tracking the bill's lifecycle (e.g., Draft, Received, Approved, Scheduled, Paid).
• total_amount: The final total amount of the bill.
• transaction_id: A foreign key linking to a payable Transaction entry.
• source_type: An enum to classify the bill's origin. Possible values include:
  • BOOKED: A finalized, auditable bill.
  • TRACK3_FORECAST: A projected bill from the Track3 CRM.
• confidence_level: A numeric value (e.g., 0-100) that indicates the probability of a TRACK3_FORECAST bill being realized.
• created_at: Timestamp of creation.
• updated_at: Timestamp of last update.

Expense

This entity represents a direct expenditure.

• expense_id: A unique identifier for the expense.
• expense_date: The date the expense occurred.
• vendor_id: An optional foreign key linking to a Vendor entity.
• description: A human-readable description of the expense.
• amount: The value of the expense.
• transaction_id: A foreign key linking to a Transaction entry.
• source_type: An enum to classify the expense's origin. Possible values are BOOKED and TRACK3_FORECAST.
• confidence_level: A numeric value indicating the probability of a TRACK3_FORECAST expense being realized.
• created_at: Timestamp of creation.
• updated_at: Timestamp of last update.

Receipt

This entity stores information about a captured receipt image.

• receipt_id: A unique identifier.
• related_entity_id: A foreign key that links the receipt to either a Bill or an Expense.
• file_url: The URL or file path where the receipt image is stored.
• upload_date: Timestamp of when the receipt was uploaded.
• created_at: Timestamp of creation.

---

Functional Requirements

• Bill and Expense Management: The system must allow users to create, edit, and track the status of both BOOKED bills and expenses. Users must be able to schedule future payments for bills.
• Receipt Capture and OCR: The system will support the upload of receipt images via a mobile app or web interface. It will integrate with an OCR service to automatically extract key data and attempt to match the receipt to an existing BOOKED expense or bill record.
• Approval Workflows: The system must allow for the creation of simple approval workflows, where a BOOKED bill must be approved by a designated user before it can be scheduled for payment.
• Automated Matching: The system will use data from bank feeds to automatically match transactions to existing BOOKED bills and expenses, updating their status to Paid.
• Forecasting Logic: The system must include a mechanism to view and filter TRACK3_FORECAST bills and expenses. These will be included in the Monthly Performance Report to provide a forward-looking view, but they will not affect standard financial statements or formal accounting.

---

Integration Points

• Track3 CRM: The system will pull projected expenses from Track3's API, creating TRACK3_FORECAST records. These will be automatically assigned a confidence_level and an expected date.
• Receipt Capture: The system will integrate with a dedicated service for mobile-first receipt capture, providing an API to upload images and receive extracted data.
• Bank Feeds: Transactions imported from integrated bank feeds will be used to automatically reconcile and mark BOOKED bills and expenses as paid.
• Audit Trail: All creation, modification, and deletion of vendors, bills, and expenses must be logged in the audit trail.