​

HouseholdOS architecture overview

​

Entry points

HouseholdOS consists of a single-page browser application, an application service for authentication and HTTP routes, and scheduled processing for recurring household work. The public marketing site is a separate application with its own routes and contact endpoint. Unmatched application navigations fall back to the single-page application so deep links can load the requested screen.

​

SPA route inventory

The SPA uses lightweight client-side routing backed by browser history. Legacy aliases /home and /dashboard redirect to /. The marketing application implements /, /features, /how-it-works, /pricing, /about, /contact, /faq, /security, /legal/terms, /legal/privacy, and a 404 page. Its contact form posts to /api/contact on the marketing origin.

​

Frontend conventions

Navigation uses links for destinations and buttons for actions such as submissions, deletions, and dialogs. Data updates appear optimistically, roll back visibly on failure, and ignore stale failures. Cross-module features share one authoritative record instead of maintaining shadow copies.

​

Authentication and authorization

Browser sign-in begins at /auth/login and establishes a same-origin application session. The SPA calls /api/me to determine whether the session is authenticated. The API accepts the application session and supported identity or access tokens. The public health check, the separately authorized readiness check, and the bearer-secret calendar subscription do not use an application session. For the calendar subscription, possession of the complete URL grants read-only access, so the URL must be kept private and regenerated if exposed. Every other API route authenticates the caller before dispatching an operation. Household access has two layers:

1. Data-layer controls scope records to the active user and household.
2. Application authorization requires active membership and checks the requested operation against role or custom permissions.

Owners can perform all household actions. Adults can work with most household records but cannot administer the household by default. Teen, Child, Guest, and Co-parent roles have smaller module-specific permission sets. Sensitive money, receipt, medical, emergency, document, contact, and custody data is not granted to those lower-trust roles by default.

​

Data model

Household-scoped data covers application modules such as bills, budgets, events, tasks, chores, shopping lists, receipts, records, notifications, and household administration. User-scoped data is limited to household selection, notification preferences, the household list, user preferences, and the user profile.

​

Recurring bills and calendar projections

The in-app calendar and provider exports share one canonical outbound projection combining events, bills, and subscriptions. The in-app /calendar view projects events and bills for its visible date range. Recurring bills support weekly, monthly, and yearly local-calendar advancement. Unsupported frequency is rejected visibly. Scheduled processing generates due notifications and chore instances.

​

Runtime configuration

Runtime configuration covers the application origin and version, identity, email, SMS, analytics, monitoring, AI services, file scanning, platform administration, and health checks. Credential names and values are intentionally not reproduced here. Database changes use ordered, reviewed migrations. Migration commands and schema implementation details are intentionally omitted from this public overview.

​

Deployment shape and repository/live boundary

The application deployment serves the browser app and handles /api/*, /auth/*, and /webhooks/* requests at app.householdos.pndsvcs.com. The marketing site deploys separately at householdos.pndsvcs.com and owns its /api/contact route. Application webhooks remain with the application service. Source verification does not deploy either application. Consequently, source behavior in this page should not be treated as proof of the currently deployed build.