Odecio Souza · Software Developer | Backend Systems, APIs & Automation · ABC Solutions
Build. Secure. Automate. Share.
The problem was real before the architecture became complicated
I started Agenda de Contas to organise household bills, track payments and plan recurring financial commitments. My household and I use it regularly, and it meets our main organisational needs. The application organises financial obligations; it does not process payments or provide regulated financial services.
The first version was an ASP.NET Core application with a browser interface and JSON-based persistence. Alongside the account and payment workflows, I developed reminders and a routine for operating the application on my own Linux infrastructure.
Later, I wanted to support individual logins and multiple families, each with its own accounts, payments, settings and permissions. That raised a more difficult question:
How could I add a multi-family architecture without putting an application I already relied on at unnecessary risk?
Keep a working baseline working
The most tempting migration plan was to replace JSON with PostgreSQL and move on. I resisted that all-at-once approach because the existing application was not a disposable prototype. It was being used in real life.
I chose to evolve the system incrementally. The documented baseline retained the original JSON store while PostgreSQL, EF Core and individual identity support were developed separately. A feature boundary kept the new multi-family path from automatically replacing the working one.
The distinction matters: code can be implemented, reviewed and merged without becoming the documented production baseline.
Here is a simplified view of the two execution paths described in the architecture documentation:
ASP.NET Core application
|
Multi-family gate
/ \
/ \
Disabled Enabled
(documented baseline) (controlled testing)
| |
ContaStore Identity + family context
| |
JSON Scoped repositories
|
PostgreSQL
The diagram omits private hosting details. It represents the documented production baseline on the left and a controlled development and test path on the right; it does not prove a PostgreSQL production cutover.
One database per family or a shared database?
One design decision involved a genuine discussion about how to isolate families.
I considered two approaches:
Give each family its own database.
Use a shared PostgreSQL database with strict logical isolation between families.
A separate database for every family can provide physical separation. But for my requirements, it would also increase the work involved in provisioning, schema migrations, maintenance and backups. I considered that complexity disproportionate for the stage of the project.
I therefore chose a shared-database design with family-scoped access.
The selected design avoids managing a database for every family, but it makes application and data isolation essential. Those boundaries were implemented and tested as part of the new architecture, not activated as a verified production cutover.
Tenant isolation needs more than FamilyId
I designed for defence in depth: membership rules, a selected-family context, repository-level scoping, relational constraints and tests that attempt to cross family boundaries.
The multi-family model contains users, families and memberships. A user's Owner, Admin or Member role belongs to their membership in a particular family, not to their identity globally. Accounts, payments, reminders and settings are family-owned. Scoped repositories and authorisation protect read access, while relational constraints help prevent invalid cross-family relationships.
Make the migration explicit and repeatable
Another challenge was the transition of existing records.
I wanted a controlled process rather than an automatic migration silently triggered on application startup. The developed importer was designed around a few principles:
Explicit execution: importing data is a deliberate operation, not a hidden side effect.
Dry-run support: the operator can inspect an intended import without writing records.
Deterministic mapping: the same source records should map consistently.
Idempotency: repeating a successful operation should not create duplicates.
Transactions: a failed operation should not leave partially migrated data.
Strict input validation: missing required JSON collections should not be mistaken for deliberately empty ones.
A concrete validation case illustrates the risk: a JSON object containing only {} should not be accepted as a successful empty import when the required collections are absent. An intentionally empty array is different from a missing or null collection. The documented importer tests this distinction rather than treating incomplete input as a reassuring zero-record result.
I learned to value clear failure behaviour more than a superficially smooth migration.
Test what must not happen
Supporting multiple families changes the security model.
It is not enough for one user to see their own records when everything is configured correctly. I also need evidence that the application rejects access to records belonging to another family.
The documented tests check tenant isolation, invalid roles and memberships, duplicate constraints and cross-family account/payment relationships.
For example, consider an attempt to associate a Family A payment with a Family B account. Repository scoping should prevent cross-family reads, and relational constraints should reject an invalid relationship. This illustrates a tested boundary using fictional families; it is not a real data-exposure incident.
Individual authentication introduced further concerns. Invitation and password-recovery flows need careful token handling and must avoid unnecessarily revealing whether an account exists. Delivery was separated from token generation so that the flows could be tested without relying on a real notification provider or embedding credentials in source code.
For relational tests, the project used disposable PostgreSQL environments. That made it possible to validate database behaviour without touching the data in my household's existing application.
Operations require separate evidence
Developing software and operating it are different kinds of responsibility.
I researched and configured Linux and Docker infrastructure, deployment routines, secure access and automated backups. This work was challenging. It involved documentation, experiments, repeated troubleshooting and learning how to verify that an operation had genuinely succeeded.
Backup hardening is a good example. The reviewed implementation added integrity checks before marking transfers complete, stronger handling of unexpected paths, and compatibility checks for legacy manifest formats.
However, a passing synthetic test is not proof of deployment or recovery on a real machine. Restores and operational activation require separate evidence.
What I would compare differently in retrospect
The separate-database versus shared-database discussion was a real architectural choice during development. Other possibilities are useful retrospective comparisons, not decisions I claim to have explicitly considered at that time.
For example, replacing JSON immediately might have shortened the transition on paper, but it would have combined data conversion with identity and tenancy changes. Relying exclusively on application query filters would reduce some schema work, but it would provide less protection against invalid relationships or missed filters. Treating roles as global would simplify early code but misrepresent permissions for users belonging to several families.
Reflecting on those alternatives has helped me explain why I prefer staged change, explicit tenant boundaries and independent validation.
What runs today and what comes next
As of 17 November 2026, repository documentation identifies JSON persistence as the documented production baseline. PostgreSQL multi-family features have been developed and tested; a live cutover has not been verified.
My household's ongoing use is real, but I am not claiming external customer adoption, commercial revenue or measured time savings. An external-user pilot remains a future milestone.
Before that pilot, I want controlled deployment evidence, an isolated database, checked backup and recovery procedures, a rehearsed import and a rollback plan.
I have learned that engineering means researching alternatives, protecting what works and separating technical progress from operational proof.
The safest migration was not the one that replaced JSON fastest. It was the one that made each consequential step explicit, testable and reversible wherever possible.
Public engineering references
The development history can be explored through public GitHub pull requests:
Agenda de Contas project
Identity and tenant isolation — PR #2
Controlled JSON import — PR #4
Family management — PR #10
Off-host backup hardening — PR #14
Transport manifest compatibility — PR #15
Verification manifest compatibility — PR #16
These references support the implementation history. They do not independently verify my household's experience or current server state.
About the author and AI assistance
I conceived and directed the project, researched technical choices, evaluated alternatives, supervised development, carried out operational work and reviewed and validated results. ChatGPT and Codex assisted materially with research, implementation, troubleshooting, tests and technical documentation. I remain responsible for the direction of the project and the accuracy of this account; I do not claim that all code was written manually without assistance.
Odecio Souza
Software Developer | Backend Systems, APIs & Automation
ABC Solutions · Build. Secure. Automate. Share.
GitHub · LinkedIn · ABC Solutions
Top comments (0)