# Project pack: Bigcapital @ 04a3a9f

Facts about **Bigcapital** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Bigcapital is open-source accounting and inventory software, a QuickBooks alternative. You can create invoices and bills, record payments, manage stock, and produce balance sheets, profit and loss and other reports based on a proper double-entry ledger. You host it on your own server with Docker.

## Version and source
- Repository: https://github.com/bigcapitalhq/bigcapital
- Pinned commit: `04a3a9f72da8f67359c3af39cddd2d8a33228211`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/bigcapitalhq/bigcapital/archive/04a3a9f72da8f67359c3af39cddd2d8a33228211.zip
- Official docs: https://docs.bigcapital.app
- Licence: **AGPL-3.0-only**. Free to use and change. If other people use your changed version, including over a network (for example a website you host for them), you must offer them your source code under the same licence. Using it privately for yourself or your household has no extra obligations.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/bigcapitalhq/bigcapital bespoke-bigcapital
  cd bespoke-bigcapital
  git checkout --detach 04a3a9f72da8f67359c3af39cddd2d8a33228211
  # Prepare development requirements and local configuration first.
  corepack enable
  pnpm install
  cp .env.example .env
  docker compose up -d
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  Follow the Docker guide at https://docs.bigcapital.app/deployment/docker, which provides the docker-compose file and environment template.
  ```

- Needs: Docker with several GB of memory; Node 22 and pnpm for development
- Develop: `docker compose up -d`
- Test: `pnpm test`
- Stack: typescript (NestJS, React, Vite, Knex, pnpm). Difficulty for a non-developer with an AI: **advanced**. A TypeScript monorepo with a server, a web app and several supporting services. Accounting rules are subtle, so changes to ledger code need real care and tests.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`.

## Customisation points (settings → extend → code)
- **chart-of-accounts** [settings]: Your accounts, currencies, tax rates and numbering. → `Accounts → Chart of accounts, Settings → Preferences`
- **invoice-templates** [settings]: Logo, colours and wording on invoices and estimates. → `Settings → Branding templates`
- **api** [extend]: Create invoices and read reports from other tools. → `docs.bigcapital.app API reference`
- **webapp-screens** [code]: New screens and list views. → `packages/webapp/src`
- **server-services** [code]: New report types and automation. → `packages/server/src`

## Must keep working
- Double-entry rules. Every transaction must balance.
- Database migrations. Add new ones; never edit old ones.
- Period locks and report totals.

## Staying updatable
Prefer branding templates, settings and the API. Add code in new modules, and test any change that touches journals.

## Data, costs and safety
- Personal data: **yes**. Stored in: A MySQL database plus an attachments store (Docker volumes). Contains your customers, invoices and financial statements. Back it up often.
- Service: Email (SMTP) (optional, usually free to a few dollars): Sending invoices and reminders.
- Service: Bank sync (Plaid) (optional, paid): Optional bank feed import.
- Setting `JWT_SECRET` (**secret**: the person enters it themselves, never in chat): Secret used to sign logins. Never paste it into an AI chat.
- Setting `DB_PASSWORD` (**secret**: the person enters it themselves, never in chat): Database password.
- It holds financial records. Keep it behind HTTPS and a strong password.
- Don't paste JWT or database secrets into an AI chat.
- Accounting rules vary by country. Check outputs with an accountant before relying on them.

---

# Customising Bigcapital

Bigcapital is a pnpm monorepo with a NestJS server and a React web app. Try settings and templates first.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Web app screens | packages/webapp/src/ |
| API, accounting engine and reports | packages/server/src/ |
| Database migrations | the migrations folder inside packages/server |
| Docker setup | docker/ and docker-compose.yml |
| End-to-end tests | e2e/ |

## Use the gentlest change first

1. **Settings (no code):** accounts, taxes, currencies, templates and numbering.
2. **Extend:** the API and exports.
3. **Code:** new screens and reports, with tests.

## Recipes

- **New report:** add a report service on the server, expose it through a controller, then add a screen in the web app.
- **New invoice field:** add a migration, include it in the model and DTO, then show it in the invoice form and template.

## Running and checking your changes

- Run the stack with `docker compose up -d` and create an invoice, receive a payment and view the balance sheet.
- `pnpm test` and the end-to-end tests in `e2e/` where relevant.
- Check that the trial balance still sums to zero.

## Pitfalls

- Never edit existing migrations.
- Changes to journal entries affect reports. Add tests with sample ledgers.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/bigcapital/04a3a9f/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/bigcapital/04a3a9f/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/bigcapital/04a3a9f/r2/SKILL.md)