New to Fincas? Read getting-started.md first, then
architecture.md. The project overview is the
README.
| Document |
What it covers |
| getting-started.md |
from pip install fincas to a first login, in a project of your own |
| packaging.md |
what the wheel ships, installing from PyPI, version pinning, the settings overlay, overriding templates |
| deployment.md |
production: environment, required secrets, Docker Compose, systemd, reverse proxy, database, scheduled jobs, operator commands |
| deploy-fly.md |
a complete Fly.io deployment, with the storefront as a second app |
| upgrading.md |
versioning, the deprecation policy, the migration contract, how to upgrade |
| releases/ |
per-release notes: what to do before upgrading, behavior changes, migrations |
| Document |
What it covers |
| architecture.md |
the app map, settings layers, the plugin seam, the storefront contract, API authentication |
| plugins.md |
writing a plugin: hooks, lifecycle signals, outbox consumers, URLs, testing |
| webhooks.md |
outbound webhooks: events, payload versions, signatures and verification |
| fields.md |
custom fields in the metadata sidecar |
| labels.md |
renaming nouns (Customer, Engagement, …) in the staff UI |
| roles.md |
staff roles, the staff flag, and how they stay in step |
| identity-unification.md |
design notes: how staff, customers and service accounts authenticate |
| formatting.md |
how money and dates are formatted across the back office, PDFs, CSV and the API |
| storefront-seo.md |
storefront URLs, metadata and structured data for categories, brands and products |
| Document |
What it covers |
| crm/importing.md |
importing from another CRM: the canonical format, dry runs, review, undo |
| crm/adapters.md |
connected accounts: Aircall, Gmail, ClickUp, Klaviyo, Google Ads, keys and erasure |
| crm/wiring.md |
wiring the adapters in a deployment: secrets, worker, scheduler, webhooks, first week |
| crm/fields/ |
field inventories for each provider and how to decide where a field goes |
| Document |
What it covers |
| CONTRIBUTING.md |
development setup, checks, how a pull request lands |
| release-testing.md |
the back-office journey harness (scripts/harness/run.sh) against any Postgres 17 |
| SECURITY.md |
reporting a vulnerability privately |
| CHANGELOG.md |
what changed in each release |
