tigerstar 0.1.0__tar.gz

tigerstar-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,29 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tools
+        run: pip install hatchling build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

tigerstar-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.idea/
+.env
+.venv/
+env/
+*.json
+uv.lock
+dist/
+*.egg-info/

tigerstar-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Eric Kweyunga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tigerstar-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: tigerstar
+Version: 0.1.0
+Summary: Double-entry ledger engine with pluggable storage backends
+Project-URL: Repository, https://github.com/erickweyunga/tigerstar
+Project-URL: Documentation, https://github.com/erickweyunga/tigerstar/tree/main/docs
+Author-email: Eric Kweyunga <maverickweyunga@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: accounting,double-entry,fintech,ledger,payments
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.12
+Provides-Extra: all
+Requires-Dist: firebase-admin>=6.0; extra == 'all'
+Requires-Dist: psycopg-pool>=3.1; extra == 'all'
+Requires-Dist: psycopg[binary]>=3.1; extra == 'all'
+Provides-Extra: firestore
+Requires-Dist: firebase-admin>=6.0; extra == 'firestore'
+Provides-Extra: postgres
+Requires-Dist: psycopg-pool>=3.1; extra == 'postgres'
+Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# TigerStar
+
+A double-entry ledger engine with pluggable storage backends.
+
+## Features
+
+- **Double-entry bookkeeping** — every transfer debits one account and credits another
+- **Two-phase transfers** — reserve funds (pending), then post or void
+- **Linked transfers** — atomic chains that all succeed or all fail
+- **Balance constraints** — prevent overdrafts with account flags
+- **Multi-currency** — separate ledgers per currency with configurable precision
+- **Financial reporting** — trial balance, balance sheet, general ledger
+- **Storage adapters** — swap between Firestore and PostgreSQL without changing application code
+- **Concurrent-safe** — row-level locking (Postgres) or optimistic transactions (Firestore)
+
+## Install
+
+```bash
+pip install tigerstar[postgres]    # PostgreSQL only
+pip install tigerstar[firestore]   # Firestore only
+pip install tigerstar[all]         # both backends
+```
+
+## Quick Start
+
+### With Firestore
+
+```python
+from tigerstar import TigerStar, FirestoreStorage
+
+storage = FirestoreStorage(credentials_path="path/to/firebase-adminsdk.json")
+engine = TigerStar(storage=storage)
+```
+
+### With PostgreSQL
+
+```python
+from tigerstar import TigerStar, PostgresStorage
+
+storage = PostgresStorage(dsn="postgresql://user:pass@localhost:5432/dbname")
+storage.migrate()
+engine = TigerStar(storage=storage)
+```
+
+### Create a ledger and move money
+
+```python
+from tigerstar import Ledger, Account, AccountType, AccountFlags, Transfer, TransferCode
+
+ledger = Ledger(currency="TZS", precision=0, max_transfer_amount=10_000_000)
+engine.create_ledger(ledger)
+
+cash = Account(ledger_id=ledger.id, code=AccountType.ASSET)
+user = Account(
+    ledger_id=ledger.id,
+    code=AccountType.LIABILITY,
+    flags=AccountFlags(debits_must_not_exceed_credits=True),
+)
+engine.create_accounts([cash, user])
+
+engine.create_transfers([
+    Transfer(
+        debit_account_id=cash.id,
+        credit_account_id=user.id,
+        ledger_id=ledger.id,
+        amount=50000,
+        code=TransferCode.PAYMENT,
+    ),
+])
+```
+
+## Storage Adapters
+
+| Adapter | Database | Best For |
+|---------|----------|----------|
+| `FirestoreStorage` | Google Cloud Firestore | Serverless, zero-ops, auto-scaling |
+| `PostgresStorage` | PostgreSQL | Financial-grade ACID, SQL flexibility, cost control |
+
+Both adapters implement the same interface — swap one for the other with zero application changes. See [docs/adapters.md](docs/adapters.md) for connection pooling, migrations, and writing custom adapters.
+
+## Documentation
+
+- [Usage Guide](docs/usage.md) — ledgers, accounts, transfers, reporting
+- [Storage Adapters](docs/adapters.md) — setup, configuration, custom adapters

tigerstar-0.1.0/README.md

@@ -0,0 +1,84 @@
+# TigerStar
+
+A double-entry ledger engine with pluggable storage backends.
+
+## Features
+
+- **Double-entry bookkeeping** — every transfer debits one account and credits another
+- **Two-phase transfers** — reserve funds (pending), then post or void
+- **Linked transfers** — atomic chains that all succeed or all fail
+- **Balance constraints** — prevent overdrafts with account flags
+- **Multi-currency** — separate ledgers per currency with configurable precision
+- **Financial reporting** — trial balance, balance sheet, general ledger
+- **Storage adapters** — swap between Firestore and PostgreSQL without changing application code
+- **Concurrent-safe** — row-level locking (Postgres) or optimistic transactions (Firestore)
+
+## Install
+
+```bash
+pip install tigerstar[postgres]    # PostgreSQL only
+pip install tigerstar[firestore]   # Firestore only
+pip install tigerstar[all]         # both backends
+```
+
+## Quick Start
+
+### With Firestore
+
+```python
+from tigerstar import TigerStar, FirestoreStorage
+
+storage = FirestoreStorage(credentials_path="path/to/firebase-adminsdk.json")
+engine = TigerStar(storage=storage)
+```
+
+### With PostgreSQL
+
+```python
+from tigerstar import TigerStar, PostgresStorage
+
+storage = PostgresStorage(dsn="postgresql://user:pass@localhost:5432/dbname")
+storage.migrate()
+engine = TigerStar(storage=storage)
+```
+
+### Create a ledger and move money
+
+```python
+from tigerstar import Ledger, Account, AccountType, AccountFlags, Transfer, TransferCode
+
+ledger = Ledger(currency="TZS", precision=0, max_transfer_amount=10_000_000)
+engine.create_ledger(ledger)
+
+cash = Account(ledger_id=ledger.id, code=AccountType.ASSET)
+user = Account(
+    ledger_id=ledger.id,
+    code=AccountType.LIABILITY,
+    flags=AccountFlags(debits_must_not_exceed_credits=True),
+)
+engine.create_accounts([cash, user])
+
+engine.create_transfers([
+    Transfer(
+        debit_account_id=cash.id,
+        credit_account_id=user.id,
+        ledger_id=ledger.id,
+        amount=50000,
+        code=TransferCode.PAYMENT,
+    ),
+])
+```
+
+## Storage Adapters
+
+| Adapter | Database | Best For |
+|---------|----------|----------|
+| `FirestoreStorage` | Google Cloud Firestore | Serverless, zero-ops, auto-scaling |
+| `PostgresStorage` | PostgreSQL | Financial-grade ACID, SQL flexibility, cost control |
+
+Both adapters implement the same interface — swap one for the other with zero application changes. See [docs/adapters.md](docs/adapters.md) for connection pooling, migrations, and writing custom adapters.
+
+## Documentation
+
+- [Usage Guide](docs/usage.md) — ledgers, accounts, transfers, reporting
+- [Storage Adapters](docs/adapters.md) — setup, configuration, custom adapters

tigerstar-0.1.0/docs/adapters.md

@@ -0,0 +1,204 @@
+# Storage Adapters
+
+TigerStar uses a storage adapter pattern. The engine doesn't care which database you use — swap the adapter and everything works the same.
+
+## Available Adapters
+
+| Adapter | Database | Best For |
+|---------|----------|----------|
+| `FirestoreStorage` | Google Cloud Firestore | Serverless, zero-ops, auto-scaling |
+| `PostgresStorage` | PostgreSQL | Financial-grade ACID, SQL flexibility, cost control |
+
+## Firestore Adapter
+
+```python
+from tigerstar import TigerStar, FirestoreStorage
+
+storage = FirestoreStorage(
+    credentials_path="path/to/firebase-adminsdk.json",
+    database_id="default",  # optional, defaults to "default"
+)
+engine = TigerStar(storage=storage)
+```
+
+### Requirements
+
+- `firebase-admin` package
+- A Firebase project with Firestore enabled
+- Service account JSON credentials
+
+### Collections Created
+
+- `ledgers`
+- `accounts`
+- `transfers`
+- `postings`
+
+### Notes
+
+- Transactions use Firestore's built-in optimistic concurrency
+- All reads happen before writes within a transaction
+- Scales automatically — no infrastructure to manage
+- Pay per read/write operation
+
+## PostgreSQL Adapter
+
+```python
+from tigerstar import TigerStar, PostgresStorage
+
+storage = PostgresStorage(
+    dsn="postgresql://user:password@localhost:5432/dbname",
+    min_size=5,   # minimum pool connections
+    max_size=20,  # maximum pool connections
+)
+storage.migrate()  # create tables on first run
+engine = TigerStar(storage=storage)
+```
+
+### Requirements
+
+- `psycopg[binary]` and `psycopg-pool` packages
+- PostgreSQL 15+ (recommended: 17+)
+
+### Connection Pooling
+
+The adapter uses `psycopg_pool.ConnectionPool` internally. Connections are reused across requests — no per-operation connection overhead.
+
+```python
+# Custom pool sizing for high-throughput
+storage = PostgresStorage(
+    dsn="postgresql://user:pass@localhost/otta",
+    min_size=10,   # keep 10 connections warm
+    max_size=50,   # burst up to 50 under load
+)
+```
+
+For production with multiple app instances, put PgBouncer in front of PostgreSQL:
+
+```python
+# Point at PgBouncer (transaction pooling mode)
+storage = PostgresStorage(
+    dsn="postgresql://user:pass@localhost:6432/otta",
+    min_size=5,
+    max_size=20,
+)
+```
+
+### Migrations
+
+Tables are created via SQL migration files in `src/storage/postgres/`.
+
+**Option 1 — via the storage instance:**
+
+```python
+storage = PostgresStorage(dsn="postgresql://...")
+storage.migrate()
+```
+
+**Option 2 — import and run directly:**
+
+```python
+import psycopg
+from tigerstar.storage.postgres import run_migrations
+
+conn = psycopg.connect("postgresql://user:pass@localhost/otta", autocommit=True)
+run_migrations(conn)
+conn.close()
+```
+
+Migrations are versioned. Each `.sql` file runs once — tracked in a `schema_migrations` table. To add a new migration, create a new file like `002_add_column.sql` in the `src/storage/postgres/` folder.
+
+### Concurrency
+
+- Uses `SELECT ... FOR UPDATE` with deterministic lock ordering
+- Account IDs are sorted before locking — prevents deadlocks
+- Ledger validation runs outside the transaction to minimize lock hold time
+- Read Committed isolation level (default) + explicit row locks
+
+### Schema Constraints
+
+The database enforces integrity at the SQL level:
+
+- `CHECK (amount > 0)` — no zero or negative transfers
+- `CHECK (debit_account_id != credit_account_id)` — can't transfer to self
+- `CHECK (debits_pending >= 0 ...)` — balances never go negative
+- Foreign keys on all references
+
+### Indexes
+
+Optimized for ledger workloads:
+
+- Covering index on `transfers(ledger_id, created_at)` — avoids heap lookups
+- Partial index on pending transfers — fast timeout queries
+- Composite index on `postings(account_id, created_at)` — fast general ledger queries
+
+## Writing a Custom Adapter
+
+Implement `StorageBase`:
+
+```python
+from tigerstar.storage.base import StorageBase
+
+class MyStorage(StorageBase):
+
+    def save_ledger(self, ledger):
+        ...
+
+    def get_ledger(self, ledger_id):
+        ...
+
+    def save_account(self, account):
+        ...
+
+    def save_accounts_batch(self, accounts):
+        ...
+
+    def get_account(self, account_id):
+        ...
+
+    def get_accounts_batch(self, account_ids):
+        ...
+
+    def save_transfer(self, transfer):
+        ...
+
+    def get_transfer(self, transfer_id):
+        ...
+
+    def save_posting(self, posting):
+        ...
+
+    def get_postings_for_transfer(self, transfer_id):
+        ...
+
+    def execute_transfer(self, transfers, account_ids, pending_ids, process):
+        """
+        Must be atomic. Steps:
+        1. Read pending transfers by pending_ids (if any)
+        2. Read and lock accounts by account_ids
+        3. Call process(accounts, pending_transfers) -> (results, updated_accounts, postings)
+        4. Write updated accounts, new transfers, and postings
+        5. Return results
+        All within a single transaction.
+        """
+        ...
+
+    def query_accounts_by_ledger(self, ledger_id):
+        ...
+
+    def query_transfers_by_ledger(self, ledger_id):
+        ...
+
+    def query_postings_by_account(self, account_id):
+        ...
+
+    def query_postings_all(self):
+        ...
+```
+
+Then use it:
+
+```python
+storage = MyStorage(...)
+engine = TigerStar(storage=storage)
+```