Members, Admins & Avatars
Relevant source files
The following files were used as context for generating this wiki page:
GoCasa manages Household participants through a system of Members and Admins. A Member represents a person or pet within the Household, while an Admin is a Member with elevated privileges and a required PIN to access system settings.
Members can have personalized visual representations via Avatars. If no image is uploaded, the system generates a fallback using the Member's initials and assigned color.
Sources: GLOSSARY.md:6-15, internal/web/settings_templ.go:20-28
Member Management
The system classifies Household participants into two roles: Member and Admin. A Member can be active or archived. Archived Members are hidden from filters and boards but retain their historical data, such as event associations and point balances.
Sources: GLOSSARY.md:9-25, internal/app/members.go:240-245
Data Schema
The members table stores core identity and security data.
| Field | Type | Constraints | Description |
|---|---|---|---|
| id | INTEGER | PRIMARY KEY | Unique identifier (never reused). |
| name | TEXT | 1-50 chars | Member display name. |
| color | TEXT | Hex format | Assigned color (e.g., #rrggbb). |
| role | TEXT | 'admin', 'member' | Access level. |
| pin_hash | BLOB | NOT NULL for Admins | Bcrypt hash of the Admin PIN. |
| archived | BOOLEAN | Default false | Indicates if Member has left. |
Sources: internal/db/migrations/0002_members.sql:2-10, internal/app/members.go:34-40
Admin Security and PINs
Admins must set a 4-to-8 digit PIN. This PIN protects sensitive actions like changing household settings or managing other Members. The system enforces a lockout policy: five consecutive wrong attempts block an Admin's PIN for five minutes.
Household Protection Rules
To prevent an accidental lockout, the system enforces the "Last Admin" rule. You cannot demote, archive, or delete a Member if they are the only active Admin remaining in the Household.
Sources: internal/app/members.go:27-28, internal/app/members.go:220-224
Avatars and Fallbacks
Members can upload images to use as avatars. The system supports JPEG, PNG, GIF, and WebP formats. Uploaded images are processed into 256x256 pixel squares.
Sources: internal/web/settings_templ.go:146, internal/app/avatar_test.go:44-55
Logic Flow for Avatar Display
If a Member has no uploaded image, the system renders a CSS-styled circle using the Member's assigned color and initials.
The system generates initials by taking the first letter of the first two words in a Member's name.
Sources: internal/web/settings_templ.go:40-62, internal/web/settings_templ.go:31-38
API Endpoints
Member and Admin actions are routed through specialized handlers, most requiring an unlocked session.
| Method | Endpoint | Description |
|---|---|---|
| GET | /settings | Displays Member list and setup status. |
| POST | /setup | Creates the first Admin (only if no Members exist). |
| POST | /lock | Validates Admin PIN to unlock settings. |
| POST | /settings/members | Adds a new Member (Admins only). |
| POST | /settings/members/{id} | Updates Member name, color, or role. |
| POST | /settings/members/{id}/archive | Hides a Member while keeping history. |
| POST | /settings/members/{id}/avatar | Uploads a new avatar image. |
Sources: internal/app/app.go:110-120, internal/app/members.go:88-100
CLI Recovery
If the last Admin forgets their PIN, the system provides a recovery command. Running gocasa reset-pin <name|id> generates a new random 6-digit PIN and clears any active wrong-PIN blocks for that account.
Sources: internal/app/members.go:258-261, internal/app/members.go:281-285
Conclusion
The Members and Admins system provides the foundational identity layer for GoCasa. By combining strict protection of the last Admin with archival capabilities and visual personalization through avatars, the system ensures household data remains secure yet accessible.