add-ideas/comiaunicaty

Fork 0

Files

Albrecht Degering 70cf1a84ca inital commit, very early alpha stage

2026-06-30 13:38:24 +02:00

17 KiB

Raw Blame History

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:

.
├── 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:

# 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:

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:

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.
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:

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:

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:

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:

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:

Remote server exposes /.well-known/group-platform.json.
Remote server can create a scoped connection token for a member/admin in dev mode.
Home server connects to a remote server using URL + token.
Home server fetches capabilities.
Home server syncs actions/events/announcements/files/threads through /api/sync.
Home dashboard displays both local and remote objects.
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:

GET /.well-known/group-platform.json
GET /api/sync?since=<cursor>

The manifest should contain:

{
  "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:

{
  "cursor": "next_cursor",
  "actions": [],
  "events": [],
  "announcements": [],
  "files": [],
  "threads": []
}

13. Responsive UI

Build a polished mobile-first UI.

Required navigation:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

A user can open the frontend.
Seed data appears.
The user can use a demo invite link and join a group without account creation.
The user can RSVP to an event.
The user can see a cross-group action dashboard.
An admin can create an invite and view migration status.
A user can link a second device/session through the pairing flow.
A user can connect a remote self-hosted server with URL + token and sync structured objects.
The UI works well on a phone-sized viewport.
Backend tests cover auth/join, permissions, actions, and remote sync.

Suggested implementation order

Scaffold backend/frontend/docker.
Implement DB models and seed data.
Implement session/auth primitives and invite flow.
Implement groups, members, announcements, events, RSVPs.
Implement home dashboard/action derivation.
Implement group dashboard UI.
Implement files, tasks, polls, threads/messages.
Implement devices/recovery/device linking.
Implement migration dashboard and reminder copy generator.
Implement remote server manifest, connection token, sync endpoint, home aggregation.
Polish UI and responsive behavior.
Add tests and README.

If time is limited, prioritize vertical completeness in this order:

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.

17 KiB Raw Blame History