Reposition Finitum as a dev-first open-source project

.github/ISSUE_TEMPLATE/add-a-bank.yml

@@ -0,0 +1,60 @@
+name: Add a bank
+description: Request support for a new bank, or start contributing a parser yourself
+title: "[bank] "
+labels: ["bank-parser"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping Finitum support more banks! Parsers are data-driven -- you can add one yourself
+        with no engine code by following [docs/adding-a-bank.md](../blob/main/docs/adding-a-bank.md).
+        If you'd rather not, fill this out with sanitized samples and someone can pick it up.
+
+        **Important: sanitize every sample.** Replace real names, account numbers, national ids, and card
+        digits with fake values of the same shape (same length/format).
+  - type: input
+    id: bank
+    attributes:
+      label: Bank name and country
+      placeholder: "e.g. Banco Estado (Chile)"
+    validations:
+      required: true
+  - type: input
+    id: senders
+    attributes:
+      label: Sender addresses
+      description: The From addresses the bank uses for notification emails.
+      placeholder: "e.g. notifications@bank.com, alerts@bank.com"
+    validations:
+      required: true
+  - type: checkboxes
+    id: types
+    attributes:
+      label: Notification types the bank sends
+      options:
+        - label: Purchases (card payments)
+        - label: ATM withdrawals
+        - label: Transfers
+  - type: textarea
+    id: samples
+    attributes:
+      label: Sanitized sample emails
+      description: |
+        For each type, paste the subject and the body (use "Show Original" in Gmail, then sanitize).
+        Keep the exact spacing/encoding artifacts -- they matter for the regexes.
+      render: text
+    validations:
+      required: true
+  - type: checkboxes
+    id: intent
+    attributes:
+      label: Contribution
+      options:
+        - label: I plan to open a PR for this parser myself
+  - type: checkboxes
+    id: sanitized
+    attributes:
+      label: Confirmation
+      options:
+        - label: I confirm the samples above contain no real personal or account data
+          required: true

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,44 @@
+name: Bug report
+description: Something isn't working
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened?
+      description: What did you do, what did you expect, and what happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. ...
+        2. ...
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Email ingestion / forwarding
+        - Bank parser (wrong amount, merchant, category...)
+        - Web app / dashboard
+        - Authentication
+        - Self-hosting / Docker
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: env
+    attributes:
+      label: Environment
+      description: Self-hosted or finitum.app? If self-hosted, how are you running it? Include relevant logs (redact secrets).
+  - type: markdown
+    attributes:
+      value: |
+        If a bank email was parsed wrongly, please include a **sanitized** copy of the email
+        (replace names, account numbers, and card digits with fake values of the same shape).
+        Never post real personal or financial data.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/richardhapb/finitum/blob/main/SECURITY.md
+    about: Please report security issues privately -- not as public issues.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,21 @@
+name: Feature request
+description: Suggest an idea or improvement
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem would this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How do you imagine it working? Alternatives you considered are welcome too.
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+## What
+
+<!-- What does this PR change and why? -->
+
+## Checklist
+
+- [ ] Tests added/updated for behavior changes (`uv run pytest`)
+- [ ] Lint passes (`uv run ruff check`)
+- [ ] For bank parsers: fixtures are sanitized (no real names, accounts, or card digits) and parametrized cases added in `tests/test_parse.py`

CLAUDE.md

@@ -0,0 +1,41 @@
+# Finitum
+
+Open-source, dev-first personal finance manager: users forward their bank notification emails to a per-user ingest address, and Finitum parses them into transactions with community-written bank parsers.
+
+## Project direction (read this first)
+
+Finitum pivoted in July 2026 from a private, Chile-only SaaS to a **worldwide, open-source, dev-first project**. The goal is to become a world-class OSS standard for email-based transaction parsing, not primarily to monetize. Implications:
+
+- **Parsers are community-contributed.** Anyone should be able to add their bank by editing data files and fixtures, without touching engine code. Optimize every change for that contributor experience.
+- **Email ingestion is via forwarding rules, not the Gmail API.** Users add a Gmail forwarding rule (or any provider's equivalent) pointing to their per-user ingest address; a Cloudflare Email Routing worker POSTs the raw MIME to `POST /ingest/email`. The old Gmail-API polling path (Celery `src/tasks/email_fetch.py`, `EmailManager` in `src/email_service/manager.py`) is legacy, gated behind `GMAIL_POLLING_ENABLED=false`, and slated for removal.
+- **Google OAuth is login-only** (`openid` + `userinfo.email` scopes, `src/oauth_service/google_oauth.py`). Never reintroduce Gmail scopes.
+- **Worldwide, not Chile-only.** Hardcoded Chilean assumptions (CLP defaults, `America/Santiago`, Spanish-only labels, Chilean merchant keywords) are legacy to be generalized, not patterns to extend.
+- A hosted cloud offering for non-technical users may exist later, but the repo is the OSS product; keep private-deployment specifics (the VPS, GHCR namespace, `finitum.app` domains) out of contributor-facing docs and templated in infra configs.
+- **Planned: outbound webhooks.** Devs should be able to subscribe to events (new transaction parsed, transfer detected, etc.) and trigger their own automations from the data. Not implemented yet; design APIs with this event surface in mind.
+
+The reference deployment is live at https://finitum.app (Lightsail VPS, deployed via the CI pipeline). Richard dogfoods it daily -- treat `main` as production.
+
+## Architecture
+
+- **Backend**: FastAPI (`src/api/server.py`), PostgreSQL + Alembic (`src/db/`, `alembic/`), Redis (dedupe + Gmail-confirmation capture).
+- **Ingestion**: `src/email_service/ingest.py` -- resolves user by `ingest_token` from the `u-<token>@<INGEST_DOMAIN>` recipient, HMAC-verifies `X-Finitum-Signature` (`INGEST_WEBHOOK_SECRET`), dedupes on `Message-ID`, auto-captures Gmail forwarding-confirmation links/codes into Redis for one-click setup. Worker lives in `infra/email-worker/`.
+- **Parsers**: fully data-driven. All bank logic lives in `src/parsers/regex.json` (per-bank: `remitents` sender allowlist, `subject` classification patterns, `body` extraction regexes). Engine: `src/parsers/parser.py` (`EmailParser`, `BankPatterns.from_json`). The bank is a per-user setting (`User.bank`); there is no content-based bank auto-detection. `GET /banks` derives the bank list from `regex.json` keys.
+- **Categories**: keyword matching in `src/parsers/base.py` from root `categories.json`; slugs/labels registry in `src/category_catalog.py`; Spanish overrides in `category_labels.es.json`; per-user custom categories via `POST /categories` + `src/db/categories.py`.
+- **Frontend**: React Router v7 + TypeScript + Tailwind + Bun in `web/` (file routes under `web/app/routes/`). `profile.tsx` holds the up-to-date forwarding-setup UX; `home.tsx` and `guide.tsx` still carry stale OAuth-era messaging.
+
+## Adding a bank (the core contributor flow)
+
+1. Add a bank block to `src/parsers/regex.json` (all body regex keys are required by `BankPatterns.from_json` validation).
+2. Add sanitized sample fixtures under `tests/banks/<bank>/` (plain text body/subject files, e.g. `purchase_clp.txt`, `purchase_subject.txt`).
+3. Add parametrized cases in `tests/test_parse.py`. Tests build `Message(...)` by hand and run `EmailParser(bank)` directly -- no network or Gmail needed.
+
+## Conventions
+
+- Python managed with `uv` (`uv.lock`, `uv sync --frozen`); lint with `ruff`; tests with `pytest`. CI in `.github/workflows/ci.yml` runs lint + tests on PRs.
+- Run everything via Docker Compose (`docker compose up --build`); API on 9090.
+- Write tests for behavior changes, especially parser changes (fixture-driven).
+- English is the canonical language for docs, code, and labels; other locales are overrides.
+
+## Known drift (do not trust these blindly)
+
+- Root `README.md` still describes the OAuth/Gmail-API model and private EC2/GHCR deploy; `web/README.md` describes a layout that no longer exists; `terms/` texts assume the Gmail-access SaaS. The roadmap lives in `plans/` (phases 1-3) and `todo.md` -- `plans/phase-3-open-source-i18n.md` is the source of truth for the OSS/i18n work (LICENSE decision, CONTRIBUTING, docs/, issue templates, SECURITY.md are still missing).

CODE_OF_CONDUCT.md

@@ -0,0 +1,73 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances
+  of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+finitumapp@gmail.com. All complaints will be reviewed and investigated promptly
+and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing to Finitum
+
+Thanks for your interest in Finitum! Contributions of all kinds are welcome, but the one we want most is simple: **add your bank**. Parsers are data-driven (JSON + regex + fixtures, no engine code), and every new bank makes Finitum useful to more people. The complete guide is [docs/adding-a-bank.md](docs/adding-a-bank.md).
+
+## Ways to contribute
+
+- **Add a bank parser** -- see [docs/adding-a-bank.md](docs/adding-a-bank.md). No Python required.
+- **Improve category detection** -- add merchant keywords to `categories.json`.
+- **Report bugs / propose features** -- use the [issue templates](https://github.com/richardhapb/finitum/issues/new/choose).
+- **Improve the core** -- backend (FastAPI), frontend (React Router), the ingest pipeline, or the docs.
+
+## Development setup
+
+The backend uses Python 3.12+ managed with [uv](https://docs.astral.sh/uv/); the frontend uses [Bun](https://bun.sh/).
+
+**Full stack via Docker (recommended for running the app):**
+
+```bash
+cp .env.example .env   # fill in the values
+docker compose up --build
+```
+
+**Backend only (for tests and linting):**
+
+```bash
+uv sync
+uv run pytest          # run the test suite
+uv run ruff check      # lint
+```
+
+Parser tests need no services at all -- they run against text fixtures in `tests/banks/`:
+
+```bash
+uv run pytest tests/test_parse.py -v
+```
+
+**Frontend:**
+
+```bash
+cd web
+bun install
+bun run dev            # dev server
+bun run typecheck      # typegen + tsc
+bun run lint           # eslint
+```
+
+## Pull requests
+
+- Branch from `main`; keep PRs focused on one change.
+- **Include tests** for anything that changes behavior. For parsers this means fixtures + parametrized cases (see the guide); CI runs `ruff` and `pytest` on every PR.
+- **Sanitize fixtures**: sample emails must not contain real names, account numbers, national ids, or card digits. Replace them with fake values of the same shape.
+- Keep the parser engine generic -- bank-specific logic belongs in `regex.json`, not in Python.
+- New user-facing text should be in English; localized labels are handled via the category catalog overrides.
+
+## Questions
+
+Open a [discussion or issue](https://github.com/richardhapb/finitum/issues), or email finitumapp@gmail.com. Security issues: please follow [SECURITY.md](SECURITY.md) instead of opening a public issue.
+
+## Code of Conduct
+
+By participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard Peña and Finitum contributors
+
+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.