Families manage money and responsibilities in ways that often resemble small organizations. They coordinate recurring contributions, fund shared projects, track obligations, resolve disputes, and follow up with members who miss payments.
Yet these activities frequently happen through group chats, spreadsheets, handwritten records, and informal agreements. The problem isn't simply that these tools lack automation. It's that they make it difficult to maintain a reliable financial history, coordinate responsibilities, and establish accountability as a family grows.
Kith was built to address that problem: bringing structured financial records, automated workflows, and accountable collaboration to family finance without imposing the complexity of enterprise software.
Building it required more than creating forms and database endpoints. Financial coordination introduces difficult engineering requirements around concurrent writes, duplicate submissions, historical integrity, scheduled work, and recoverable notifications.
This article explores the architectural decisions behind those requirements.
- Financial History Must Remain Auditable
In an ordinary CRUD application, updating a record in place is often sufficient. In a financial system, silently changing a confirmed transaction can undermine the history that other decisions depend on.
Kith uses an append-oriented ledger model. Once an entry is confirmed, corrections are represented through new entries linked to the original rather than by silently replacing the original transaction.
The relationship between an original entry and its correction is cryptographically linked, providing a mechanism for connecting the financial history and detecting inconsistencies according to the implemented verification rules.
Database-level immutability enforcement provides another layer of protection. The database, rather than application conventions alone, prevents confirmed entries from being modified in place through the protected database operations.
This distinction matters because application-level validation cannot protect a record against every other database access path. Integrity rules are stronger when they are enforced at the layer responsible for storing the data.
The objective is straightforward: preserve the original financial event, make corrections explicit, and maintain an auditable history of how the record evolved.
- Idempotency and Duplicate-Submission Defense
Financial applications must account for unreliable networks, repeated button clicks, client retries, and requests that succeed even when the client never receives the response.
Consider a contribution request that reaches the server and commits successfully. If the response is lost, the client may retry. Without duplicate protection, the same logical contribution could be recorded twice.
Kith uses client-supplied idempotency keys to associate retries with the original logical operation.
The important part is not merely checking whether a key already exists. Concurrent requests can both pass an application-level check before either inserts its record. That check-then-insert pattern leaves a race condition.
Kith's duplicate-submission handling has been hardened to close that race, so the idempotency mechanism must be evaluated as a complete concurrency-safe operation rather than as a preliminary lookup.
A separate ten-minute heuristic identifies likely accidental duplicate contributions. This heuristic serves a different purpose from idempotency: it can warn users about suspiciously similar submissions without automatically rejecting every legitimate repeated contribution.
The distinction is important:
- Idempotency identifies repeated attempts at the same logical operation.
- Duplicate heuristics identify separate operations that may represent an accidental repeat.
Keeping these mechanisms separate avoids confusing network retries with legitimate contributions.
- Atomic State Transitions With PostgreSQL
Financial coordination involves operations that update several related records. Dispute resolution, invitation acceptance, and converting an event into a recurring pool are examples where partial completion can leave the application in an inconsistent state.
If two requests modify related data concurrently, individually valid operations can still produce an invalid combined result.
Kith addresses these cases using PostgreSQL transactions and atomic RPC functions for critical multi-step writes. Where appropriate, row locking coordinates competing operations so that they cannot independently proceed on stale assumptions about the same protected state.
The objective is to keep related changes within a single transactional boundary.
For example, a critical state transition should not update one record successfully and then leave its related records unchanged because a subsequent operation failed.
Moving these transitions into the database reduces the number of application-level steps that can interleave with competing requests and makes the consistency boundary explicit.
This approach does not eliminate the need to reason about isolation levels, lock ordering, or transaction failures. It provides a mechanism for enforcing the invariants that those operations require.
- Proxy Membership: Designing for Families With Different Technical Abilities
Not every family member can or wants to use a mobile application.
A household may need to record contributions or assign responsibilities for a baby, an elderly relative, or someone who does not use digital tools independently.
Kith addresses this through proxy membership.
An authorized administrator can manage participation on behalf of a proxy member while maintaining an explicit relationship between the proxy and the accountable manager.
Actions performed on behalf of a proxy are separately recorded, preserving accountability without requiring every participant to operate an account independently.
This is more than a convenience feature. It introduces a distinct authorization question: who is performing an action, and on whose behalf is that action being performed?
Maintaining that distinction allows the application to support family circumstances without treating every action as if the affected member performed it personally.
- Unattended Automation With BullMQ
Recurring financial activities should not depend on an administrator remembering to trigger every operation manually.
Kith uses nine Redis-backed BullMQ queues and scheduled jobs to coordinate recurring pools, reminders, notifications, cleanup tasks, and member-engagement updates.
Recurring pool management
Recurring pools require predictable lifecycle transitions. Kith generates upcoming cycles three months ahead of time and automates scheduled opening and closing.
Where configured, unpaid balances can carry forward into the next cycle as adjusted targets rather than being represented as payments that never occurred.
This preserves the distinction between an outstanding obligation and an actual contribution.
Recoverable notifications
Notification delivery introduces an external dependency. A job can be processed successfully by the application while the downstream email or push provider rejects the delivery or becomes unavailable.
Kith uses an outbox-oriented workflow to record delivery state and a recovery sweep that runs every five minutes to identify and re-enqueue eligible stuck deliveries.
This makes failures observable and creates a recovery path for transient problems instead of silently discarding work.
It does not mean every external delivery is guaranteed to succeed. Permanent provider failures and other terminal errors still require appropriate failure handling.
Scheduled maintenance
Background workers also handle overdue-payment reminders, task-status updates, invitation cleanup, and member-engagement recomputation.
Moving this work out of user-facing requests keeps routine operations from depending on a user remaining online or an administrator manually initiating each step.
- Security Beyond Authentication
Financial records require protection at several levels, not just a login screen.
Kith includes authorization and validation mechanisms designed to reduce the risk of information disclosure and unauthorized changes.
Tenant isolation
Workspace membership checks return a uniform not-found response when access cannot be established. This avoids revealing whether a particular resource exists to an unauthorized requester.
File integrity validation
Payment proofs, task evidence, and milestone photographs undergo file-signature validation using actual file contents rather than relying solely on client-declared content types.
This helps detect files whose contents do not match their claimed formats.
Administrative safeguards
The application prevents the last remaining active workspace administrator from being removed or demoted.
Administrative dashboard access is also restricted through IP allowlisting and timing-safe Basic Authentication verification.
These controls address different risks: authorization mistakes, misleading file metadata, accidental loss of administrative access, and unauthorized access to privileged interfaces.
They should be understood as layers of protection rather than as a claim that any single mechanism makes the entire application secure.
Conclusion
Kith began with a familiar problem: families need to coordinate shared finances and responsibilities, but informal tools become difficult to manage as those relationships grow more complex.
Solving that problem required engineering beyond ordinary CRUD operations. Financial history needed explicit integrity rules, concurrent writes needed safe state transitions, repeated requests needed duplicate protection, and background workflows needed observable failure handling and recovery.
The broader lesson is that trustworthy financial software depends on making important invariants explicit and enforcing them at the appropriate layer.
For Kith, the goal is to combine that engineering discipline with an interface and workflow that remain accessible to the people using it: families coordinating money, responsibilities, and trust.
