comiaunicaty/CODEX_TASK.md

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