Savvy

Someone who wants to manage money according to Islamic obligation has to do it on paper or in a spreadsheet. Mainstream budgeting apps have no concept of zakat — you cannot ask them what 2.5% of your zakatable wealth is, because they do not know which of your assets are zakatable or what the nisab threshold is this year. They have no way to mark a loan as interest-bearing and treat that differently from an interest-free one. Planning for qurbani, hajj, or a cousin's wedding means keeping a separate goal-tracking sheet, then manually reconciling it against a bank statement at the end of the month. The reconciliation step is the expensive one: reading a PDF statement line by line and typing each transaction into a category is an hour of work that people simply stop doing after the second month.

Solo build, no budget for paid infrastructure during development, so everything had to run on a laptop via Docker Compose and still be deployable to a real cluster without a rewrite. Bank statements are the input and there is no aggregator API for Pakistani banks — statements arrive as PDF, CSV, or XLSX exports with wildly inconsistent formats, so parsing had to be tolerant rather than strict. The data is financial and personally identifying (CNIC numbers, IBANs, account numbers), which pushed encryption, PII log masking, and per-user database isolation from "later" into the first pass. And the AI path costs real money per call, so the design had to assume an adversarial user trying to burn API credits.

Seven FastAPI services, each with its own PostgreSQL database and its own Docker network. The obvious alternative was a modular monolith, which for a solo project would have been faster to build — I chose services anyway because the statement-analysis path has a completely different resource profile from CRUD: it is long-running, memory-heavy, and calls a paid external API, and I wanted to be able to scale and rate-limit that independently. The Kubernetes HPAs reflect this — api-gateway scales 2→8, finance-service and bank-service 2→6, ai-recommendation-service 1→4, all at 70% CPU target. The cost is real: finance-service cannot join against bank-service tables, so anything cross-domain goes through Kafka events rather than SQL.

Auth is centralised at the gateway and nowhere else. The gateway validates the JWT, injects X-User-ID, and signs the forwarded request with HMAC-SHA256 (shared/utils/service_auth.py, ±30s replay tolerance) so a downstream service can prove the request came from the gateway rather than from a compromised sibling container. Downstream, finance-service takes that header, sets SET LOCAL app.user_id on the transaction, and lets PostgreSQL RLS policies enforce ownership on all 11 user-owned tables — so a missing WHERE user_id = ... in application code returns zero rows instead of another user's expenses. Defence in depth, deliberately: the ORM filters, and the database refuses. Statement processing is fully asynchronous — the upload endpoint returns as soon as the file is in S3 and the event is published, because AI extraction of a 12-month PDF is not something to hold an HTTP connection open for.

It started as a specific irritation rather than a product idea. I wanted to plan for zakat, qurbani, and a set of upcoming family expenses in the same place I tracked ordinary spending, and every app I tried treated the religious obligations as if they did not exist. The original brief I wrote for myself is still in the repo as Project Brief.txt — it is one long paragraph, half feature list and half wishful thinking, and reading it now the thing that stands out is how much of it survived.

I got the AI part backwards at first. My assumption was that Claude would do the categorisation and the deterministic code would just be glue. That is expensive and it is fragile — one API outage and the core feature returns nothing. The rewrite inverted it: deterministic categorisation is the default path, the vector store makes it better over time, and the model is used for the one thing rules genuinely cannot do, which is turning a wall of ragged PDF text into structured rows. The confidence score in confidence_scorer.combine exists because of that inversion — I needed a single number that says how much to trust a row regardless of which tier produced it.

The moment it clicked was writing the RLS policies. Up to that point security was a checklist I was working through. Running a query with the wrong app.user_id and watching PostgreSQL return zero rows for data I knew was there reframed it: the question stopped being "did I remember the filter" and became "what still holds when I forget". Everything after that — HMAC between services, the six-network topology where database containers are unreachable by non-owning services, the PII masking filter attached at the logging layer so no future logger.info can leak a CNIC — came out of that same question.

What I would do differently: I would not have committed this as two commits. The whole build happened locally and landed in one drop, which means the git history records nothing about where the difficulty actually was — the three rewrites of the categorisation pipeline, the RLS-versus-Alembic fight, the switch from SET to SET LOCAL. All of that is reconstructable from the code and the comments I left, but it should have been in the log. I would also have written the integration tests earlier. 479 unit tests is a reasonable number, and they are concentrated exactly where I was least confident — 46 in the recommendation service, 43 on gateway auth, 33 on categorisation — but they all mock Kafka, Redis, S3, and Claude, which is why a live bug like the health-score endpoint querying ZakatRecord.calculated_at and is_paid when the model actually has calculation_date and payment_status sat there undetected. The unit tests cannot see it. A single end-to-end run would have.

Module 1 shipped: 115 routed API endpoints across 7 services, 4 PostgreSQL databases with Alembic migrations, RLS on all 11 user-owned finance tables, a Kafka event bus with 5 typed event families, ChromaDB-backed categorisation, and a Next.js frontend covering 16 dashboard pages including zakat, qurbani, sadaqah, hajj/umrah, net worth, and the Islamic financial health score. 479 tests run in CI across a 7-service matrix, with pip-audit, bandit, npm audit, and Trivy image scanning on every push plus a weekly CVE sweep.

Not shipped: production deployment. The EKS manifests, HPAs, cert-manager issuer, external-secrets bindings, and the 11 numbered bootstrap scripts are written and the repo's own status section marks it as pending cloud provisioning — nothing has run against a real cluster. The four security items the catalogue marks partial or deferred (K8s Secrets among them) are still open.

Savvy is a distributed, event-driven financial management system with 6 independent FastAPI microservices (User, Finance, Bank, Statement Analysis, AI Recommendation, Notification), each with a dedicated PostgreSQL database. Services communicate exclusively via Kafka (20+ event types) — no synchronous inter-service HTTP.

The Statement Analysis service uses Claude AI to extract and categorize every transaction from uploaded PDF/CSV/Excel bank statements with confidence scoring. The AI Recommendation service runs a 7-node LangGraph workflow: Expense Pattern Analysis → Income Assessment → Goal Gap Analysis → Market Research (yfinance) → Shariah Compliance Screening → Risk Assessment → Claude synthesis. Islamic finance features include a full Zakat calculator (Nisab threshold + 2.5% on zakatable wealth), Qurbani savings goals, and Shariah-compliant investment filtering. The frontend is a Next.js glassmorphism UI with Framer Motion and Recharts.