README
Hip Hip Groups & Sharing (P029)
Group-based list sharing for the Hip Hip todo app. Create groups, invite members via link, share todo lists with role-based access control.
Quick Start
Backend
bash
cd backend
docker compose up --build
Backend serves GraphQL at http://localhost:8080/query with playground at http://localhost:8080/.
Frontend
bash
cd frontend
npm install
npm run dev
Frontend dev server at http://localhost:5173, proxies GraphQL to backend.
Prerequisites
- Go 1.25+
- Node.js 20+
- Docker & Docker Compose (for PostgreSQL)
Features
- Groups: Create, update, delete groups with custom name, description, icon, and color
- Invitations: Invite members via cryptographically secure link (7-day expiry)
- Roles: Admin, Member, Viewer with enforced permission matrix
- List Sharing: Share personal todo lists with groups; group members get access based on role
- Dataloaders: Batch-loading prevents N+1 queries for group members and lists
- Avatar Colors: Random color assignment from 8-color palette on registration
Architecture
Hexagonal architecture (ports & adapters) extending P026/P028:
shell
Domain → Ports → App Services → Adapters (PostgreSQL, GraphQL, JWT, bcrypt)
New Backend Components
| Component | Path | Description |
|---|---|---|
| Group domain | internal/domain/group.go | Group, GroupMembership, Invitation entities with validation |
| GroupService | internal/app/group_service.go | Business logic for groups, invitations, memberships, sharing |
| GroupRepo | internal/adapters/postgres/group_repo.go | Group CRUD |
| MembershipRepo | internal/adapters/postgres/membership_repo.go | Membership queries with batch loading |
| InvitationRepo | internal/adapters/postgres/invitation_repo.go | Token-based invitation management |
| Migrations 5-9 | internal/adapters/postgres/migrations/ | Groups, memberships, invitations, FK, avatar color |
New Frontend Components
| Component | Path | Description |
|---|---|---|
| GroupCard | src/components/GroupCard.tsx | Group preview card with member avatars |
| MemberList | src/components/MemberList.tsx | Member list with role management (admin view) |
| MemberAvatar | src/components/MemberAvatar.tsx | Colored circle with user initials |
| InviteModal | src/components/InviteModal.tsx | Email invite form with copy-link |
| GroupsPage | src/pages/GroupsPage.tsx | Grid of user's groups |
| GroupViewPage | src/pages/GroupViewPage.tsx | Group detail with shared lists |
| GroupSettingsPage | src/pages/GroupSettingsPage.tsx | Admin-only group settings |
| InvitationPage | src/pages/InvitationPage.tsx | Accept/decline invitation via token |
GraphQL API
New Queries
myGroups: [Group!]!— All groups the user belongs togroup(id: ID!): Group!— Single group with members and listsinvitationInfo(token: String!): InvitationInfo!— Public invitation details (no auth required)
New Mutations
createGroup,updateGroup,deleteGroup— Group CRUDinviteMember,acceptInvitation,declineInvitation— Invitation flowremoveMember,updateMemberRole— Membership managementshareList— Share a personal list with a group
Role-Based Authorization
| Operation | Admin | Member | Viewer |
|---|---|---|---|
| View group/lists/items | Yes | Yes | Yes |
| Update/delete group | Yes | No | No |
| Invite/remove members | Yes | No | No |
| Leave group (self-remove) | Yes | Yes | Yes |
| Share own list | Yes | Yes | No |
| Create/edit/delete items | Yes | Yes | No |
| Update/delete list metadata | Creator or Admin | Creator only | No |
Running Tests
Backend
bash
cd backend
go test ./... # All tests
go test ./... -v # Verbose
Frontend
bash
cd frontend
npm test # All tests
npm run test:watch # Watch mode
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
| DATABASE_URL | Yes | — | PostgreSQL connection string |
| JWT_SECRET | Yes | — | Secret for JWT token signing |
| PORT | No | 8080 | HTTP server port |
| VITE_API_URL | No | http://localhost:8080/query | GraphQL endpoint (frontend) |