Skip to content

README.md

Latest commit

 

History

History
204 lines (155 loc) · 6.86 KB

README.md

File metadata and controls

204 lines (155 loc) · 6.86 KB

OpenTreasury

Open-source treasury management application for NGOs. Helps administrative staff track bank transactions, income, and expenses with categories, subcategories, and tags for proper financial oversight.

Designed to be extensible — any non-profit organization can fork, configure, and deploy to their own Azure subscription.

Architecture

Layer Technology Hosting
Frontend Angular 19+, Angular Material, MSAL Angular Azure Static Web Apps (Free)
Backend Python FastAPI, async Cosmos DB SDK Azure App Service B1
Database Azure Cosmos DB NoSQL (Serverless) ~€1-5/month
Auth Microsoft Entra ID (your tenant) Employees only
IaC Bicep GitHub Actions

Estimated monthly cost: ~€20-25

graph TD
    Users["👤 Users"] -->|HTTPS| SWA
    SWA -->|"Bearer token"| API
    API -->|"async SDK"| Cosmos
    API -.->|secrets| KV
    API -.->|telemetry| AI

    SWA["Azure Static Web Apps<br/>Angular SPA + Entra ID Login<br/><i>Free tier</i>"]
    API["App Service B1<br/>Python FastAPI<br/>+ Managed Identity"]
    KV["Key Vault"]
    AI["App Insights"]

    subgraph CosmosDB["Cosmos DB NoSQL · Serverless"]
        T["transactions"]
        C["categories"]
        R["reference_data"]
        A["audit_log"]
    end
    Cosmos --- T
    Cosmos --- C
    Cosmos --- R
    Cosmos --- A
    Cosmos["Cosmos DB Account"]

    style Users fill:#f3e5f5,stroke:#ce93d8,color:#4a148c
    style SWA fill:#e8d5f5,stroke:#b39ddb,color:#4a148c
    style API fill:#d7c4e8,stroke:#9575cd,color:#311b92
    style Cosmos fill:#c5e1a5,stroke:#aed581,color:#33691e
    style CosmosDB fill:#f1f8e9,stroke:#c5e1a5,color:#33691e
    style T fill:#fff9c4,stroke:#fff176,color:#f57f17
    style C fill:#fff9c4,stroke:#fff176,color:#f57f17
    style R fill:#fff9c4,stroke:#fff176,color:#f57f17
    style A fill:#fff9c4,stroke:#fff176,color:#f57f17
    style KV fill:#fce4ec,stroke:#f48fb1,color:#880e4f
    style AI fill:#e0f7fa,stroke:#80deea,color:#006064
Loading

Project Structure

opentreasury/
├── frontend/          Angular 19 app (standalone components, MSAL auth)
├── api/               Python FastAPI backend
│   └── tests/         Backend test suite (pytest)
├── infra/             Bicep IaC (Cosmos DB, App Service, SWA, Key Vault, App Insights)
│   ├── modules/       Reusable Bicep modules
│   └── parameters/    Environment-specific parameter files (dev, prod)
├── docs/              Architecture docs, feature specs, security reviews
├── scripts/           Azure setup and teardown scripts
├── .github/workflows/ CI/CD pipelines + Squad automation
└── .squad/            AI team state (Squad coordination)

Deploy to Your Azure

OpenTreasury is built for any organization to run on their own Azure subscription. Your data stays in your account — you own it completely.

Estimated cost: €15-25/month for a small organization.

What you'll need:

  • An Azure subscription
  • Admin access to your Microsoft Entra ID tenant
  • A private GitHub repository

Get started:

  1. Copy the contents of deploy-template/ to a new private repo
  2. Follow the step-by-step Deployment Guide
  3. Run the setup script, configure GitHub, and trigger the workflow — done!

Most organizations are up and running in about an hour.

Prerequisites

  • Node.js 20+
  • Python 3.11+
  • Angular CLI (npm install -g @angular/cli)
  • Azure CLI (for deployment)

Quick Start

Frontend (with mock data — no backend needed)

cd frontend
npm install
npx ng serve

Open http://localhost:4200 — logs in as a mock Admin user with 25 sample transactions.

The frontend runs with mock data by default (useMocks: true in environment.ts). All API calls are intercepted and return realistic sample data. To connect to a real backend, see Connecting Frontend to Backend.

Backend

cd api
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

pip install -r requirements.txt
cp .env.example .env
# Edit .env with your Azure credentials

uvicorn app.main:app --reload --port 8000

API docs at http://localhost:8000/api/docs (Swagger UI, dev only — disabled in production).

Connecting Frontend to Backend

In frontend/src/environments/environment.ts, set:

useMocks: false,
apiBaseUrl: 'http://localhost:8000/api',

And configure the MSAL settings with your Entra ID app registration.

Environment Variables (Backend)

Variable Description Example
AZURE_TENANT_ID Entra ID tenant xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AZURE_CLIENT_ID Backend app registration client ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
COSMOS_ENDPOINT Cosmos DB account endpoint https://cosmos-opentreasury.documents.azure.com:443/
COSMOS_DATABASE_NAME Database name opentreasury

Features

MVP

  • ✅ Transaction entry with categories, subcategories, and tags
  • ✅ Multi-account support (4 bank accounts + PayPal)
  • ✅ "Guardar y Nuevo" flow for fast daily data entry (~15s per transaction)
  • ✅ Transaction search and filtering (account, date, category, tag, text)
  • ✅ Category/subcategory management
  • ✅ Tag management
  • ✅ Bank account management
  • ✅ Excel/CSV import from bank exports
  • ✅ Excel export for accounting firm
  • ✅ Dashboard with account balances and monthly summary
  • ✅ Multi-language support (Spanish + English)
  • ✅ RBAC: Admin (full access) / Viewer (read-only)
  • ✅ Audit trail on all changes
  • ✅ Soft deletes (financial data is never permanently lost)

Planned

  • Invoice file attachments
  • PowerBI analytics integration
  • Multi-currency support

RBAC

Role Access
Admin Full read/write. Manages transactions, categories, tags, accounts.
Viewer Read-only. Views transactions, reports, exports. Board members.

Roles are assigned via Entra ID app roles.

Cosmos DB Containers

Container Partition Key Purpose
transactions /partitionKey ("YYYY-MM") Financial transactions
categories /id Categories with embedded subcategories
reference_data /type Tags + bank accounts
audit_log /entityType Audit trail (7-year TTL)

License

Apache License 2.0 — see LICENSE.

Contributing

See CONTRIBUTING.md for development setup, code style, and PR process.

Documentation