inital commit, very early alpha stage
This commit is contained in:
329
PRODUCT_SPEC.md
Normal file
329
PRODUCT_SPEC.md
Normal file
@@ -0,0 +1,329 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user