Homechart Documentation

Homechart is a web-based platform designed for organizing and managing household data. It serves as a central hub for family coordination, offering features such as:

• Centralized Data: A single place for all household information to prevent duplication.
• Unified Calendar: Planning for events, meals, chores, and more.
• Financial & Project Management: Linking budgets, projects, and shopping lists.
• Household Synchronization: Reminders for tasks, meals, and events.
• Family Support: Designed to accommodate extended, divorced, and blended families.
• Multilingual Support: Available in English, Arabic (عربي), German (Deutsch), Spanish (Español), French (Francais), Hindi (हिन्दी), Dutch (Nederlands), and Chinese (中文).
• Privacy & Security: No ads, no data selling, and supports both cloud-based and self-hosted deployment models.

Homechart is a Go-based server with low resource requirements. You can deploy it using either standalone binaries or containers.

Minimum Requirements

• CPU: 1
• RAM: 512MB

Deployment Methods

• Binaries: Best for running as a Linux service (e.g., via systemd).
• Containers: Requires a runtime like Docker, Podman, or Kubernetes.

Note on Mobile Apps: If you use the Homechart App Store or Play Store apps with a self-hosted instance, you must keep your server updated. Compatibility is generally maintained for client versions within +/- 3 months of the server version.

Labels allow for fine-grained access control within a component. By assigning a Label to an object, you can grant a Household member Edit, View, or None access to that specific Label, which applies to all objects sharing that Label.

Example: A user can have None permission for the entire Budget component, but still be granted Edit access to specific Budget Accounts via Label permissions.

Constraint: Session-level permissions control Label permissions. If a Session has None permissions for a component (e.g., Budget), any Label permissions for items within that component will be ignored.

Meal Times organize when Meal Plans occur and help Homechart group recipes by meal type (e.g., Breakfast, Lunch, Dinner).

Homechart includes default meal times, but you can create custom ones (e.g., Snack) to better organize your schedule.

Homechart performs all secret operations on the client using the following security model:

• Data Encryption: Secrets > Values are encrypted using 128-bit AES-GCM via standard Web Crypto APIs.
• Key Management: The Encryption Key for a Vault is encrypted using the 2048-bit RSA-OAEP Public Key of every household member with access to that Vault.
• Storage: The encrypted encryption key is stored alongside the Vault data.
• Scope: All Values within a single Vault share the same encryption key.

The Plan module integrates with several other Homechart modules to provide a unified experience:

• Budget: Associate Plan > Projects with a Budget > Category.
• Calendar: Plan > Tasks with due dates/times are automatically displayed in the Calendar.
• Shop: Plan > Projects can contain Shop > Items.

In Homechart, Address Books act as organizational containers for Contacts.

• Address Books: Organize your contacts. Every account and household has a default Address Book, but you can add additional ones. For Household Address Books, you can grant access to specific household members.
• Contacts: Store details for people, businesses, restaurants (used in [Cook]), or stores (used in [Shop]). Contacts reside within an Address Book, meaning they inherit the sharing permissions of that book. Contacts can also store integration-specific settings, such as a default Budget Category or travel time for Cook Meal Plans.

The Calendar view automatically integrates with other Homechart modules:

• Budget: Displays Budget > Recurring Transactions.
• Cook: Manages Cook > Meal Plans.
• Health: Manages Health > Logs.
• Plan: Displays Plan > Tasks.
• Shop: Can automatically add ingredients from your Cook > Meal Plan to your Shop > Pick Up list.

The Cloud and Self-Hosted servers are built with Go. The following security measures are implemented:

• Password Hashing: User passwords are hashed using the Argon2 algorithm.
• SQL Injection Prevention: The server uses parameterized queries to prevent SQL injection attacks.
• Authentication Testing: An extensive authentication and authorization test suite is run for every pull request and build.
• Minimal Third-Party Dependencies: Third-party library usage is limited and reviewed.
• Supply Chain Security: Every pull request and build requires a clean govulncheck.

An Inventory > Collection acts as a filtered view of your items. Collections allow you to:

• Select Columns: Choose which Properties are displayed in the view.
• Filter Data: Display items based on specific property values (e.g., a Collection where Location equals Attic).
• Group Items: Use Collections to represent physical containers, such as naming a Collection after a storage tote and adding all its contents to it.

The Homechart API acts as the central orchestrator and web server. Its primary responsibilities include:

• Security: Authenticating and authorizing client requests and rate limiting clients.
• Interface: Providing a REST API and serving REST API documentation via Swagger.
• Data Management: Validating request formats and performing CRUD operations on the database.
• Background Tasks: Running jobs such as sending emails and push notifications.
• Connectivity: Proxying access to Homechart Cloud for self-hosted users.
• Serving: Delivering the UI's HTML, JavaScript, and static assets.

For high availability, the API can be deployed in multiple instances. These instances coordinate through the database layer to manage distributed job running and caching.