Hearthside is a self-hosted personal and household assistant I am building in Python and Django. Its purpose is to bring practical tools for planning, remembering, and managing everyday life into one configurable home without forcing every capability into the same application or data model.
It is also a project in which I can make the engineering decisions that become increasingly important as software grows: where responsibilities belong, how components depend on one another, what happens when an operation only partly succeeds, and how behaviour remains understandable as new functionality is added.
The problem
Personal tools often emerge one at a time. Each may solve its own problem well, but the collection gradually creates another problem: configuration is duplicated, information is fragmented, and remembering where a particular capability lives becomes work in itself.
Hearthside is intended to provide a common platform around those tools while preserving their individual purposes. A household should be able to use the applications that are useful to it without needing to adopt an all-or-nothing system.
The longer-term design therefore separates shared platform concerns from specialised applications. Common capabilities can be provided once, while individual applications retain their own interfaces and ownership of their domain data.
Engineering approach
I am building Hearthside as a system that is expected to evolve rather than as a collection of isolated features.
That affects several of the choices I make:
- Clear boundaries. Shared concerns belong in the platform foundation; application-specific behaviour should remain with the application that owns it.
- Explicit state. Multi-step workflows are modelled in terms of what has actually happened rather than what was intended to happen.
- Recoverable failure. When part of an operation succeeds and another part fails, the system should preserve the valid work and provide a sensible route forward.
- Behaviour-focused testing. Tests cover state transitions, failure paths, expiry and recovery as well as straightforward successful cases.
- Continuous quality controls. Static typing, linting and automated tests are part of normal development rather than cleanup work deferred until later.
The aim is not to remove complexity by hiding it. It is to put that complexity in understandable places and make the resulting behaviour predictable.
A representative example: partial failure
The account foundation provides a useful example of that approach.
Creating an account and delivering its activation email are two separate events. The database operation may succeed even when email submission fails. Treating that situation as though account creation never happened would misrepresent the actual state of the system and could make recovery more difficult.
Hearthside therefore retains the pending account and allows activation to be sent again. Similarly, following an activation link is distinct from completing activation: opening the link does not itself activate the account or consume the token.
This is a relatively small workflow, but it illustrates a principle I want to apply throughout the project: distinguish the states the system can really be in, decide deliberately which actions cause transitions between them, and make failure states recoverable where possible.
Architecture
Hearthside currently consists of a Django deployment project and a separately installable foundation package in the same uv workspace, backed by PostgreSQL.
The package boundary separates reusable platform behaviour from deployment-specific configuration without requiring the two to be developed in separate repositories. Related changes can therefore be implemented and tested together while the architectural distinction remains explicit.
Future applications will build on that foundation rather than being absorbed into it. They can use shared platform capabilities while retaining responsibility for their own domain behaviour and data.
One candidate for a future Hearthside application is a reimplementation of my existing task-management prototype, which I already use in day-to-day life. Whether that becomes the first application built on the shared foundation will depend on which household need is most useful to address next, but it provides a concrete example of the kind of specialised application Hearthside is intended to support.
Development practices
The project uses pytest, branch coverage reporting, strict mypy checking, and Ruff.
I use these tools primarily to constrain future change. The interesting question is not simply whether the current implementation works, but whether a later change can accidentally alter behaviour that the system depends on.
For stateful workflows in particular, this means testing more than the successful path. Current tests exercise cases such as expired or superseded links, rejected state transitions, delivery failures, reserved account data, and recovery behaviour.
The browser-side code is also tested and type-checked rather than being treated as outside the project's engineering standards.
Current development
The shared account and administration foundation is the first substantial part of Hearthside being built.
It currently covers the account lifecycle: initial administration, account creation and activation, authentication, password recovery, account changes, and the recovery behaviour needed when those operations do not complete normally.
This work is deliberately establishing shared behaviour before feature applications are added. The visible interfaces are therefore currently functional development interfaces rather than the eventual household-facing design.
Source availability
I intend Hearthside to become open source.
For now, the repository remains private because the project is still taking shape and is not yet in a state I would consider useful for other people to adopt or build on. Publishing a repository creates expectations about what is usable, supported, or reasonably stable; I would rather make it public once its maturity better matches those expectations.
This is a temporary development-stage decision rather than an intention to keep the project closed.
Direction
The current foundation is only the beginning of Hearthside. The longer-term goal is a modular platform through which different personal and household support applications can be discovered, configured, and used together.
As those applications are added, the project will increasingly test the decisions being made now: whether the shared abstractions are genuinely reusable, whether application boundaries remain clear, and whether the system can grow without becoming harder to understand or maintain.
That evolution is part of what makes Hearthside useful to me as an engineering project: it provides a real problem domain in which architectural decisions have consequences beyond a single demonstration feature.