comiaunicaty/PRODUCT_SPEC.md

# PRODUCT_SPEC.md

## Product name placeholder

Use a neutral working name in code and UI, such as **GroupHome**. Keep it easy to rename.

## Product thesis

Groups remain stuck on WhatsApp-like messengers because switching costs are social, not technical. The product lowers switching costs by making the group itself movable and by making the new home materially better than chat: structured events, files, announcements, member management, tasks, polls, commitments, migration tracking, browser-first access, and no mandatory account on first use.

The product must not become a universal inbox. It must become a command center for group life.

## Target users

Primary:

- sports clubs;
- school and parent groups;
- tenant associations;
- volunteer organizations;
- local campaigns and civic groups;
- small professional or nonprofit communities.

Secondary:

- members who belong to several groups and need a unified action view;
- admins who want to leave WhatsApp without excluding people.

## Positioning

For organizations:

> Run your group professionally without forcing members onto WhatsApp.

For members:

> See what matters across all your groups without reading every chat.

For admins:

> Announcements, events, files, RSVPs, and members in one place.

For anti-lock-in positioning:

> Your group should not depend on one company's messenger.

## Required product flows

### Flow A: Admin creates a group and starts migration

1. Admin opens app.
2. Admin creates group with name, description, visibility, and default permissions.
3. Admin adds seed members manually or imports a simple CSV.
4. Admin creates invite link.
5. Admin gets QR-ready URL and WhatsApp reminder copy.
6. Migration dashboard tracks invited/opened/joined/verified/notification-enabled.
7. Admin can mark the WhatsApp channel as legacy and set a transition deadline.

### Flow B: Member joins without login

1. Member taps invite link from WhatsApp/email/SMS/QR.
2. Browser opens join screen.
3. Member sees group preview and official reason for moving.
4. Member enters/accepts display name.
5. Member is assigned a browser session/device.
6. Member can immediately read official updates and perform one useful action, such as RSVP.
7. Member is then nudged to save access via recovery email, passkey-ready protection, or browser notifications.

### Flow C: Multi-group home

1. Anna belongs to FC Kreuzberg U12, Class 4B Parents, Tenant Association, and Food Bank Volunteers.
2. Anna opens Home.
3. Home shows:
   - missing RSVPs;
   - open votes;
   - tasks assigned to Anna;
   - changed events;
   - important announcements;
   - catch-up summary of chatter.
4. Anna does not need to open every group chat.

### Flow D: Multi-device access

1. Anna joined on phone.
2. On PC, Anna opens the app and chooses “Link from existing device.”
3. PC displays code/QR.
4. Phone approves the pending device.
5. PC receives a session.
6. Anna sees both devices in Me → Devices.
7. Anna can revoke a device.

### Flow E: Self-hosted remote aggregation

1. Club runs `club.example` as a group server.
2. Anna's home server is `home.example` or the hosted default.
3. Club server creates a scoped connection token for Anna.
4. Anna connects `club.example` to her home server.
5. Home server syncs structured objects through `/api/sync`.
6. Anna's Home dashboard shows club actions alongside other groups.
7. No group data is replicated peer-to-peer between unrelated servers.

## Top-level navigation

Use these nav items:

```text
Home
Calendar
Groups
Files
Me
```

Chat must not be top-level navigation.

## Home screen details

The Home screen must include the following cards/sections:

### Needs me

High priority, actionable objects:

- RSVP required;
- vote required;
- task assigned;
- file requires acknowledgement;
- direct mention;
- admin request.

Each card must show:

- group name;
- type badge;
- due date/time if any;
- primary action button;
- source server when remote.

### Today / Upcoming

Unified agenda with:

- events;
- deadlines;
- changed locations/times;
- RSVP status;
- attached file indicators.

### Changed since last visit

Examples:

- event changed;
- new official announcement;
- task reassigned;
- poll result finalized;
- file uploaded.

### Official updates

Announcements and admin posts, separated from discussion chatter.

### Catch up

Rule-based summary in MVP:

```text
While you were away:
- 2 official announcements
- 1 event changed
- 3 open actions
- 47 discussion messages
```

Do not require AI to implement catch-up. AI hooks can be future work.

## Group page details

Default group dashboard sections:

```text
Important now
Upcoming
Open actions
Announcements
Files
Discussions
Members/Admin tools
```

Example for sports team:

```text
FC Kreuzberg U12 Parents
- Match Saturday, RSVP open
- Training moved to Pitch 2
- 3 drivers still needed
- Files: Season schedule, Emergency contacts
- Discussions: Snacks, Carpool
```

## Composer behavior

When creating group content, allow explicit content types:

```text
Announcement
Event
Task
Poll
Question/thread
File
Chat message
```

MVP can implement simple forms for each type. Later AI can suggest structure from natural language; do not block MVP on that.

## Notifications

Implement preferences by type, not only by group.

User settings:

```text
Immediate
- direct mentions
- event changes
- urgent announcements
- tasks assigned to me

Digest
- normal discussions
- new files
- photos/general chatter

Muted
- reactions
- off-topic chatter
```

UI must make the pitch clear:

> Mute the noise, not the group.

## Search and files

At MVP level:

- global file list;
- by-group filter;
- simple text search over names/descriptions;
- upload/download local files;
- show source server for remote files.

Later enhancements can include full-text search across messages.

## Migration kit details

Admin dashboard should show:

```text
31 invited
24 opened
21 joined
14 enabled notifications
4 verified recovery
7 not reached
```

Generate reminder copy, for example:

```text
23 of 31 people have joined our new group space.
The match schedule, RSVP, and files are now here: {link}
From {date}, official announcements will only be posted there.
```

WhatsApp export import:

- accept `.txt` export;
- parse basic lines if format is recognized;
- store as archive items;
- do not treat imported messages as active verified members;
- make archive clearly read-only.

## Self-hosting and aggregation

Definitions:

- Group server: canonical owner of one or more groups.
- Home server: stores a user's personal dashboard config and remote server connections.
- Remote server connection: scoped link from a home server to a group server.
- Federation: server-to-server peer network. Explicitly not included.

V2 self-hosting target:

- A server can be self-hosted by an organization.
- A user can connect multiple servers to their home profile.
- A home server aggregates structured objects.
- Servers expose an open, documented, versioned sync API.
- Users can export their data/config.

## Copy guidelines

Avoid words that create friction:

- Avoid “register” as first action.
- Avoid “create account” before value.
- Avoid “federation” in end-user UI.
- Avoid “token” in end-user UI.

Use:

- “Open group”
- “Join this group”
- “Save access”
- “Protect access”
- “Link another device”
- “Connect another group server”
- “Get updates without WhatsApp”

## What not to build

- Do not put chat as the whole product.
- Do not require the native app.
- Do not bridge or scrape WhatsApp.
- Do not make localStorage the source of identity.
- Do not force all self-hosted servers into one federation.
- Do not hide important state in chronological messages.