Settings Interface

Relevant source files

The following files were used as context for generating this wiki page:

• internal/web/settings_templ.go
• internal/app/members.go
• internal/app/app.go
• GLOSSARY.md
• internal/config/config.go
• README.md

The Settings Interface manages the administrative configuration of a GoCasa household. It provides tools for managing Members, Calendar Feeds, and overall system security through an Admin PIN system. Only users designated as Admins can access and modify these settings.

The interface is server-rendered using Go templates and includes a first-run setup flow for initializing the household. It serves as the central hub for defining who belongs to the household and what external integrations are active.
Sources: GLOSSARY.md:14-22, internal/web/settings_templ.go:121-125

Core Data Structures

The interface relies on two primary models to represent state within the web layer.

Structure	Field	Type	Description
Member	ID	int64	Unique identifier for the household member.
	Name	string	Display name (max 50 chars).
	Color	string	Hex color code (#rrggbb) assigned to the member.
	Role	string	"admin" or "member".
	Archived	bool	True if the member is hidden from active pickers.
	HasAvatar	bool	True if a custom image is uploaded.
Feed	ID	int64	Unique identifier for the iCal feed.
	Name	string	Label for the calendar feed.
	LastSuccess	string	Timestamp of the last successful sync.
	Failures	int	Count of consecutive sync failures.
	LastError	string	Error message from the most recent failure.

Sources: internal/web/settings_templ.go:17-35

Setup and Initialization

If no members exist in the database, GoCasa triggers a first-run setup. This process creates the first Admin. The first Admin must provide a name, a color, and a PIN of 4 to 8 digits.

The diagram shows the logic flow when accessing the Settings path, originating from the initial application state.
Sources: internal/app/members.go:103-125, internal/web/settings_templ.go:61-82

Security and Locking

Access to the Settings Interface is protected by a PIN-based lock system. While viewing the dashboard is generally open, administrative actions require an Unlock.

PIN Management

• Admins: Only Members with the "admin" role have a PIN.
• Locking: Admins can manually lock the session via the "Lock now" button (POST /lock/now).
• Failed Attempts: The system blocks an Admin after 5 wrong attempts for 5 minutes.
• Reset: If an Admin forgets their PIN, it can be reset via the CLI command gocasa reset-pin.

Sources: internal/app/members.go:153-200, GLOSSARY.md:24-27, internal/app/app.go:133-138

Security Flow

This sequence demonstrates the challenge-response flow for accessing administrative functions.
Sources: internal/app/members.go:167-200, internal/app/app.go:145-147

Member Management

The Settings Interface facilitates the lifecycle of a Household Member. Members are people or pets categorized into "Admins" (required to have a PIN) and "Members".

Member Lifecycle

1. Creation: Requires name, color, and role. Admins require a PIN.
2. Avatar: Users can upload pictures (JPEG, PNG, GIF, WebP). If no avatar is uploaded, the UI renders initials on the Member's chosen color.
3. Archiving: Members who have left the household are archived. They are hidden from filters but their historical event/chore data is preserved.
4. Deletion: A Member can only be deleted if they have no associated history (foreign key constraint).

Sources: internal/web/settings_templ.go:104-120, internal/app/members.go:210-275, GLOSSARY.md:29-32

Calendar Feeds

The interface manages external read-only iCal or webcal feeds (e.g., school calendars).

• Sync Data: The interface displays the "Last Success" time and consecutive "Failures" with the last error message.
• Configuration: Requires a Name, URL (typically starting with webcal://), and a display color.
• Removal: Feeds can be removed via POST /settings/feeds/{id}/delete.

Sources: internal/web/settings_templ.go:28-35, internal/web/settings_templ.go:189-215

API Endpoints

The following endpoints handle Settings operations. All POST requests to /settings/* paths (except /setup and /lock) require the session to be unlocked by an Admin.

Method	Endpoint	Action
GET	/settings	Displays the settings dashboard.
POST	/setup	Creates the first admin member.
POST	/lock/now	Immediately locks the administrative session.
POST	/settings/members	Adds a new household member.
POST	/settings/members/{id}	Updates existing member details.
POST	/settings/members/{id}/avatar	Uploads a profile picture.
POST	/settings/members/{id}/archive	Hides a member while preserving history.
POST	/settings/feeds	Adds a new external iCal feed.

Sources: internal/app/app.go:127-142

The Settings Interface ensures that household administration remains secure while providing the flexibility to manage the evolving composition of the house and its external data integrations. It combines strict server-side validation with a generated frontend to maintain data integrity across the app.db SQLite backend.
Sources: README.md:1-5, internal/app/members.go:37-55