inital commit, very early alpha stage
This commit is contained in:
656
CODEX_TASK.md
Normal file
656
CODEX_TASK.md
Normal file
@@ -0,0 +1,656 @@
|
||||
# CODEX_TASK.md
|
||||
|
||||
You are Codex. Build this project from scratch as a runnable monorepo.
|
||||
|
||||
## Goal
|
||||
|
||||
Implement a browser-first, mobile-first group coordination platform that helps groups migrate away from WhatsApp-style chaotic chats by replacing the stream with structured coordination: events, announcements, files, member management, tasks, polls, commitments, catch-up, notification preferences, and cross-group aggregation.
|
||||
|
||||
The product must support:
|
||||
|
||||
- Accountless invite-link joining.
|
||||
- Later device recovery through email, passkey-compatible architecture, QR/device linking, or admin resend.
|
||||
- A home-server concept: each user can have a home profile on a home server that stores their group memberships and remote server connection config.
|
||||
- Multiple self-hosted servers without full federation.
|
||||
- Aggregation across servers through scoped remote connections.
|
||||
- A responsive React/Vite UI optimized for phone browsers first.
|
||||
- A FastAPI backend that can run as both a home server and a group server.
|
||||
|
||||
Do not implement full federation. Do not implement native apps. Do not implement unofficial messenger bridges.
|
||||
|
||||
## Deliverables
|
||||
|
||||
Create a repository with this shape:
|
||||
|
||||
```text
|
||||
.
|
||||
├── backend/
|
||||
│ ├── app/
|
||||
│ │ ├── main.py
|
||||
│ │ ├── core/
|
||||
│ │ ├── db/
|
||||
│ │ ├── models/
|
||||
│ │ ├── schemas/
|
||||
│ │ ├── routers/
|
||||
│ │ ├── services/
|
||||
│ │ └── tests/
|
||||
│ ├── pyproject.toml
|
||||
│ └── README.md
|
||||
├── frontend/
|
||||
│ ├── src/
|
||||
│ │ ├── app/
|
||||
│ │ ├── components/
|
||||
│ │ ├── features/
|
||||
│ │ ├── routes/
|
||||
│ │ ├── api/
|
||||
│ │ ├── styles/
|
||||
│ │ └── test/
|
||||
│ ├── package.json
|
||||
│ └── README.md
|
||||
├── docker-compose.yml
|
||||
├── .env.example
|
||||
├── README.md
|
||||
└── AGENTS.md
|
||||
```
|
||||
|
||||
Use a different clean structure only if there is a strong technical reason. Document the reason.
|
||||
|
||||
## Development commands
|
||||
|
||||
Implement commands equivalent to:
|
||||
|
||||
```bash
|
||||
# from repo root
|
||||
docker compose up --build
|
||||
|
||||
# backend only
|
||||
cd backend
|
||||
python -m app.db.seed
|
||||
pytest
|
||||
uvicorn app.main:app --reload
|
||||
|
||||
# frontend only
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev
|
||||
npm run test
|
||||
npm run build
|
||||
```
|
||||
|
||||
Prefer modern package tooling, but do not let tooling block the implementation.
|
||||
|
||||
## Core product behavior
|
||||
|
||||
### 1. Accountless join flow
|
||||
|
||||
A group admin can create a group and generate invite links.
|
||||
|
||||
A recipient opens an invite link in a browser and can immediately:
|
||||
|
||||
- see the group name, purpose, and limited preview;
|
||||
- join with a display name;
|
||||
- read official announcements;
|
||||
- see upcoming events;
|
||||
- RSVP to an event;
|
||||
- participate in chat/comments if permissions allow;
|
||||
- choose notification/recovery options later.
|
||||
|
||||
Do not require email, password, social login, or native app install before first useful action.
|
||||
|
||||
Implement:
|
||||
|
||||
- Invite tokens stored as hashes.
|
||||
- One-time or limited-use invite links.
|
||||
- Session cookie issued after invite claim.
|
||||
- Device record attached to the member.
|
||||
- Revocation/reset by admin.
|
||||
|
||||
### 2. Progressive identity
|
||||
|
||||
Users start as membership-bound participants. They may later create or attach a home profile.
|
||||
|
||||
Implement trust levels:
|
||||
|
||||
```text
|
||||
Guest link can view public/limited content
|
||||
Invite member joined via invite link
|
||||
Claimed browser browser session/device is attached
|
||||
Verified contact email verified for recovery/notifications
|
||||
Passkey-ready model/API/UI support for passkey registration/login
|
||||
Full home profile aggregates multiple memberships and servers
|
||||
```
|
||||
|
||||
If full WebAuthn/passkey implementation is feasible in the pass, implement it. Otherwise create clean backend routes, frontend UI, and a pluggable `PasskeyProvider` interface with a development provider. The rest of the product must not depend on passkeys working in production mode.
|
||||
|
||||
User-facing copy should say “Save access on this device” or “Protect access,” not “Create account” as the first step.
|
||||
|
||||
### 3. Multi-device access
|
||||
|
||||
Implement at least two working paths:
|
||||
|
||||
1. **Recovery link** by email in development mode. If SMTP is not configured, log the link/code to the backend console and show a dev hint in the UI.
|
||||
2. **Link another device** via QR/code pairing:
|
||||
- new device starts pairing and receives a code;
|
||||
- existing device approves the pending code;
|
||||
- new device completes pairing and receives a session;
|
||||
- the device list shows both devices;
|
||||
- user/admin can revoke a device.
|
||||
|
||||
Model the architecture so passkey sign-in can be added cleanly.
|
||||
|
||||
### 4. Structured group objects
|
||||
|
||||
Implement these first-class objects:
|
||||
|
||||
- Announcements
|
||||
- Events
|
||||
- RSVPs
|
||||
- Tasks
|
||||
- Polls
|
||||
- Files
|
||||
- Threads/messages
|
||||
- Members
|
||||
- Devices
|
||||
- Notification preferences
|
||||
- Commitments/action items
|
||||
- Migration status
|
||||
|
||||
Chat exists, but it is not the product center. Structured cards should appear in the group dashboard and home dashboard.
|
||||
|
||||
### 5. Home dashboard for multi-group users
|
||||
|
||||
The home page must answer “What needs my attention?” across all groups and connected servers.
|
||||
|
||||
Implement sections:
|
||||
|
||||
```text
|
||||
Needs me
|
||||
Today / Upcoming
|
||||
Changed since last visit
|
||||
Official updates
|
||||
Catch up
|
||||
```
|
||||
|
||||
Action item examples:
|
||||
|
||||
- missing RSVP;
|
||||
- task assigned to me;
|
||||
- poll I have not answered;
|
||||
- event changed;
|
||||
- file requiring acknowledgement;
|
||||
- direct mention or admin question.
|
||||
|
||||
The dashboard should group by urgency and consequence, not only chronology.
|
||||
|
||||
### 6. Group dashboard
|
||||
|
||||
The group page must not default to a raw chat feed.
|
||||
|
||||
Implement a group dashboard with:
|
||||
|
||||
```text
|
||||
Important now
|
||||
Upcoming events
|
||||
Open actions
|
||||
Official announcements
|
||||
Files
|
||||
Active discussions
|
||||
Members / admin tools depending on role
|
||||
```
|
||||
|
||||
Chat or discussion threads can be one tab/section, but not the first or only concept.
|
||||
|
||||
### 7. Calendar
|
||||
|
||||
Implement a cross-group calendar view:
|
||||
|
||||
- all events from local memberships;
|
||||
- events from connected remote servers after sync;
|
||||
- RSVP status;
|
||||
- event location;
|
||||
- attached files;
|
||||
- changed-event indicators;
|
||||
- simple list view optimized for mobile.
|
||||
|
||||
Calendar export can be a later enhancement. Add TODO or stub if not implemented.
|
||||
|
||||
### 8. Files
|
||||
|
||||
Implement file metadata and upload/download for local groups.
|
||||
|
||||
Minimum:
|
||||
|
||||
- upload file to local storage in dev mode;
|
||||
- show file list by group and globally;
|
||||
- role/permission checks;
|
||||
- file attached to event/announcement when useful;
|
||||
- safe filenames and size limits.
|
||||
|
||||
### 9. Migration kit
|
||||
|
||||
Implement practical migration features:
|
||||
|
||||
- admin-created invite link/QR-ready URL;
|
||||
- member migration status: invited, opened, joined, verified, notification-enabled;
|
||||
- WhatsApp reminder copy generator;
|
||||
- “legacy channel” status flag;
|
||||
- optional WhatsApp chat export importer for `.txt` export files, stored as an archive, not as live bridged chat.
|
||||
|
||||
The app must never require or use WhatsApp APIs.
|
||||
|
||||
### 10. Notification preferences
|
||||
|
||||
Implement data model and UI for notification preferences:
|
||||
|
||||
```text
|
||||
Immediate:
|
||||
- direct mentions
|
||||
- event changes
|
||||
- urgent admin announcements
|
||||
- tasks assigned to me
|
||||
|
||||
Quiet / digest:
|
||||
- discussions
|
||||
- new files
|
||||
- photos/general chatter
|
||||
|
||||
Mute:
|
||||
- reactions/off-topic messages
|
||||
```
|
||||
|
||||
Backend should store preferences. Implement in-app notification behavior and email dev-mode notifications/digests if feasible. Web push can be a future adapter if not implemented.
|
||||
|
||||
### 11. Home server and self-hosted aggregation
|
||||
|
||||
Every server instance can act as:
|
||||
|
||||
- a group server: owns canonical groups and their data;
|
||||
- a home server: stores a user's home profile and remote server connection config;
|
||||
- both.
|
||||
|
||||
A user belongs to a home server. The home server stores config for remote servers.
|
||||
|
||||
Implement these concepts:
|
||||
|
||||
```text
|
||||
HomeProfile
|
||||
RemoteServerConnection
|
||||
RemoteMembership
|
||||
RemoteSyncCursor
|
||||
RemoteCapability
|
||||
RemoteActionItem cache
|
||||
```
|
||||
|
||||
A remote group server exposes a structured sync API. A home server connects to it with a scoped token and aggregates structured objects.
|
||||
|
||||
Important: this is **not federation**. Servers do not replicate groups peer-to-peer. A home server simply acts as a client to the remote servers selected by the user.
|
||||
|
||||
Implement a minimal remote connection flow:
|
||||
|
||||
1. Remote server exposes `/.well-known/group-platform.json`.
|
||||
2. Remote server can create a scoped connection token for a member/admin in dev mode.
|
||||
3. Home server connects to a remote server using URL + token.
|
||||
4. Home server fetches capabilities.
|
||||
5. Home server syncs actions/events/announcements/files/threads through `/api/sync`.
|
||||
6. Home dashboard displays both local and remote objects.
|
||||
7. Remote objects are marked clearly with their source server/group.
|
||||
|
||||
Store sensitive remote tokens server-side, not in browser localStorage. Use localStorage only for non-sensitive hints such as last selected home server URL or UI preferences.
|
||||
|
||||
### 12. Open protocol seed
|
||||
|
||||
Expose:
|
||||
|
||||
```text
|
||||
GET /.well-known/group-platform.json
|
||||
GET /api/sync?since=<cursor>
|
||||
```
|
||||
|
||||
The manifest should contain:
|
||||
|
||||
```json
|
||||
{
|
||||
"server_name": "Example Group Server",
|
||||
"api_base": "http://localhost:8000/api",
|
||||
"protocol_version": "0.1",
|
||||
"capabilities": {
|
||||
"events": true,
|
||||
"tasks": true,
|
||||
"files": true,
|
||||
"chat": true,
|
||||
"polls": true,
|
||||
"federation": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The sync endpoint should return structured objects, not just raw chat messages:
|
||||
|
||||
```json
|
||||
{
|
||||
"cursor": "next_cursor",
|
||||
"actions": [],
|
||||
"events": [],
|
||||
"announcements": [],
|
||||
"files": [],
|
||||
"threads": []
|
||||
}
|
||||
```
|
||||
|
||||
### 13. Responsive UI
|
||||
|
||||
Build a polished mobile-first UI.
|
||||
|
||||
Required navigation:
|
||||
|
||||
```text
|
||||
Home
|
||||
Calendar
|
||||
Groups
|
||||
Files
|
||||
Me
|
||||
```
|
||||
|
||||
Required screens:
|
||||
|
||||
- Join invite screen
|
||||
- Home dashboard
|
||||
- Calendar
|
||||
- Group list
|
||||
- Group dashboard
|
||||
- Group discussions/chat
|
||||
- Group admin / migration dashboard
|
||||
- Event detail + RSVP
|
||||
- Announcement detail
|
||||
- Task detail
|
||||
- Poll detail
|
||||
- File list and upload
|
||||
- Me/profile
|
||||
- Devices
|
||||
- Notification preferences
|
||||
- Connected servers
|
||||
- Connect remote server
|
||||
|
||||
Design requirements:
|
||||
|
||||
- bottom navigation on mobile;
|
||||
- responsive desktop layout with side navigation;
|
||||
- cards for action items, events, announcements, files, and discussions;
|
||||
- clear “official” vs “discussion” visual distinction;
|
||||
- accessible form labels and keyboard behavior;
|
||||
- loading and empty states;
|
||||
- seed-data demo should look credible immediately.
|
||||
|
||||
Use a coherent design system: spacing scale, typography, elevation, badges, status colors, rounded cards, and compact mobile layouts.
|
||||
|
||||
### 14. Seed data
|
||||
|
||||
Create seed data that demonstrates the concept:
|
||||
|
||||
- FC Kreuzberg U12 Parents
|
||||
- Class 4B Parents
|
||||
- Tenant Association
|
||||
- Food Bank Volunteers
|
||||
|
||||
Include users/members:
|
||||
|
||||
- Anna Müller as the main demo user
|
||||
- Coach Mark
|
||||
- Lisa Becker
|
||||
- Samir Khan
|
||||
- Priya N.
|
||||
- Tenant admin
|
||||
|
||||
Include events:
|
||||
|
||||
- football match with missing RSVP;
|
||||
- training location changed;
|
||||
- parent evening;
|
||||
- tenant vote deadline;
|
||||
- volunteer shift.
|
||||
|
||||
Include actions:
|
||||
|
||||
- RSVP required;
|
||||
- vote required;
|
||||
- task assigned;
|
||||
- file acknowledgement;
|
||||
- direct mention.
|
||||
|
||||
Include files:
|
||||
|
||||
- season schedule;
|
||||
- emergency contacts;
|
||||
- meeting minutes;
|
||||
- school form.
|
||||
|
||||
Include discussions:
|
||||
|
||||
- snack coordination;
|
||||
- carpool planning;
|
||||
- maintenance issue;
|
||||
- volunteer supplies.
|
||||
|
||||
### 15. API shape
|
||||
|
||||
Implement or approximate these endpoints.
|
||||
|
||||
Auth/session:
|
||||
|
||||
```text
|
||||
GET /api/health
|
||||
GET /api/me
|
||||
POST /api/auth/invite/{token}/claim
|
||||
GET /api/join/{token}/preview
|
||||
POST /api/auth/recovery/request
|
||||
POST /api/auth/recovery/consume
|
||||
POST /api/auth/device-link/start
|
||||
POST /api/auth/device-link/approve
|
||||
POST /api/auth/device-link/complete
|
||||
GET /api/me/devices
|
||||
DELETE /api/me/devices/{device_id}
|
||||
POST /api/auth/passkeys/register/options
|
||||
POST /api/auth/passkeys/register/verify
|
||||
POST /api/auth/passkeys/login/options
|
||||
POST /api/auth/passkeys/login/verify
|
||||
```
|
||||
|
||||
Home/aggregation:
|
||||
|
||||
```text
|
||||
GET /api/home
|
||||
GET /api/home/actions
|
||||
GET /api/home/calendar
|
||||
GET /api/home/files
|
||||
GET /api/home/official-updates
|
||||
GET /api/home/catch-up
|
||||
```
|
||||
|
||||
Groups:
|
||||
|
||||
```text
|
||||
GET /api/groups
|
||||
POST /api/groups
|
||||
GET /api/groups/{group_id}
|
||||
PATCH /api/groups/{group_id}
|
||||
POST /api/groups/{group_id}/invites
|
||||
GET /api/groups/{group_id}/members
|
||||
PATCH /api/groups/{group_id}/members/{member_id}
|
||||
```
|
||||
|
||||
Structured objects:
|
||||
|
||||
```text
|
||||
GET /api/groups/{group_id}/announcements
|
||||
POST /api/groups/{group_id}/announcements
|
||||
GET /api/groups/{group_id}/events
|
||||
POST /api/groups/{group_id}/events
|
||||
POST /api/events/{event_id}/rsvp
|
||||
GET /api/groups/{group_id}/tasks
|
||||
POST /api/groups/{group_id}/tasks
|
||||
PATCH /api/tasks/{task_id}
|
||||
GET /api/groups/{group_id}/polls
|
||||
POST /api/groups/{group_id}/polls
|
||||
POST /api/polls/{poll_id}/vote
|
||||
GET /api/groups/{group_id}/files
|
||||
POST /api/groups/{group_id}/files
|
||||
GET /api/files/{file_id}/download
|
||||
GET /api/groups/{group_id}/threads
|
||||
POST /api/groups/{group_id}/threads
|
||||
POST /api/threads/{thread_id}/messages
|
||||
```
|
||||
|
||||
Migration:
|
||||
|
||||
```text
|
||||
GET /api/groups/{group_id}/migration
|
||||
POST /api/groups/{group_id}/migration/reminder-copy
|
||||
POST /api/groups/{group_id}/migration/import-whatsapp-export
|
||||
```
|
||||
|
||||
Notifications/preferences:
|
||||
|
||||
```text
|
||||
GET /api/me/notification-preferences
|
||||
PATCH /api/me/notification-preferences
|
||||
GET /api/me/notifications
|
||||
PATCH /api/me/notifications/{notification_id}/read
|
||||
```
|
||||
|
||||
Remote/self-hosted aggregation:
|
||||
|
||||
```text
|
||||
GET /.well-known/group-platform.json
|
||||
GET /api/sync?since=<cursor>
|
||||
POST /api/connection-tokens
|
||||
GET /api/remote/servers
|
||||
POST /api/remote/servers/connect
|
||||
POST /api/remote/servers/{connection_id}/sync
|
||||
DELETE /api/remote/servers/{connection_id}
|
||||
```
|
||||
|
||||
### 16. Data model
|
||||
|
||||
Use a practical relational schema. Include at least:
|
||||
|
||||
```text
|
||||
HomeProfile
|
||||
HomeDevice
|
||||
RecoveryMethod
|
||||
Session
|
||||
Group
|
||||
Member
|
||||
MemberDevice
|
||||
MemberInvite
|
||||
Announcement
|
||||
Event
|
||||
EventRsvp
|
||||
Task
|
||||
Poll
|
||||
PollOption
|
||||
PollVote
|
||||
FileAsset
|
||||
Thread
|
||||
Message
|
||||
NotificationPreference
|
||||
Notification
|
||||
ActionItem
|
||||
MigrationState
|
||||
AuditLog
|
||||
RemoteServerConnection
|
||||
RemoteMembership
|
||||
RemoteSyncCursor
|
||||
RemoteCachedObject
|
||||
ConnectionToken
|
||||
```
|
||||
|
||||
A user can have a HomeProfile, but joining a group must not require one. A Member can exist without a HomeProfile. Later, a Member can attach to a HomeProfile.
|
||||
|
||||
### 17. Permissions
|
||||
|
||||
Implement simple roles:
|
||||
|
||||
```text
|
||||
owner
|
||||
admin
|
||||
moderator
|
||||
member
|
||||
guest
|
||||
```
|
||||
|
||||
Enforce at least:
|
||||
|
||||
- only admins/owners can create invite links;
|
||||
- only admins/owners/moderators can create official announcements;
|
||||
- members can RSVP, vote, comment, and complete their tasks;
|
||||
- file upload can be configured but default to members;
|
||||
- migration dashboard is admin-only;
|
||||
- remote connection tokens are scoped.
|
||||
|
||||
### 18. Security requirements
|
||||
|
||||
- Store invite tokens and recovery tokens as hashes.
|
||||
- Use HttpOnly, Secure-in-production, SameSite cookies for sessions.
|
||||
- Add CSRF protection for cookie-authenticated mutating requests, or document and implement a safe dev alternative.
|
||||
- Use server-side storage for remote tokens.
|
||||
- Do not place long-lived remote access tokens in localStorage.
|
||||
- Validate upload size/type.
|
||||
- Sanitize filenames.
|
||||
- Add audit logs for admin actions, invite creation, device linking, token creation, remote connection changes.
|
||||
- Provide `.env.example` with secrets and configuration.
|
||||
- Make dev mode explicit.
|
||||
|
||||
### 19. README
|
||||
|
||||
Create a root README that explains:
|
||||
|
||||
- product concept;
|
||||
- what is implemented;
|
||||
- quick start;
|
||||
- seed accounts/flows;
|
||||
- how to join via invite link;
|
||||
- how to link another device;
|
||||
- how to create a remote connection between two local server instances;
|
||||
- architecture overview;
|
||||
- security model;
|
||||
- limitations and next steps.
|
||||
|
||||
### 20. Quality bar
|
||||
|
||||
The final app must be demonstrable without manually editing the database.
|
||||
|
||||
At minimum, after setup:
|
||||
|
||||
1. A user can open the frontend.
|
||||
2. Seed data appears.
|
||||
3. The user can use a demo invite link and join a group without account creation.
|
||||
4. The user can RSVP to an event.
|
||||
5. The user can see a cross-group action dashboard.
|
||||
6. An admin can create an invite and view migration status.
|
||||
7. A user can link a second device/session through the pairing flow.
|
||||
8. A user can connect a remote self-hosted server with URL + token and sync structured objects.
|
||||
9. The UI works well on a phone-sized viewport.
|
||||
10. Backend tests cover auth/join, permissions, actions, and remote sync.
|
||||
|
||||
## Suggested implementation order
|
||||
|
||||
1. Scaffold backend/frontend/docker.
|
||||
2. Implement DB models and seed data.
|
||||
3. Implement session/auth primitives and invite flow.
|
||||
4. Implement groups, members, announcements, events, RSVPs.
|
||||
5. Implement home dashboard/action derivation.
|
||||
6. Implement group dashboard UI.
|
||||
7. Implement files, tasks, polls, threads/messages.
|
||||
8. Implement devices/recovery/device linking.
|
||||
9. Implement migration dashboard and reminder copy generator.
|
||||
10. Implement remote server manifest, connection token, sync endpoint, home aggregation.
|
||||
11. Polish UI and responsive behavior.
|
||||
12. Add tests and README.
|
||||
|
||||
If time is limited, prioritize vertical completeness in this order:
|
||||
|
||||
```text
|
||||
invite join → group dashboard → event RSVP → home actions → admin migration → device linking → remote aggregation
|
||||
```
|
||||
|
||||
Do not spend all effort on the chat feature. The product is structured coordination.
|
||||
Reference in New Issue
Block a user