AGENTS.md

Project mission

Build a browser-first group coordination platform that lowers dependence on WhatsApp-style group chats by giving organizations and members a better structured alternative: events, announcements, files, member management, tasks, polls, commitments, catch-up, and cross-group aggregation.

The product is not a universal chat bridge. It is an exit ramp for groups. WhatsApp or other messengers may be represented only through manual migration aids, imports, digests, and invite/reminder copy.

Required stack

Use this stack unless the existing repository already has a strong conflicting convention:

Backend: Python, FastAPI, Pydantic, SQLAlchemy, SQLite by default, optional PostgreSQL configuration.
Frontend: React, Vite, TypeScript.
Styling: mobile-first responsive UI. Prefer Tailwind CSS or a clean CSS-variable design system if Tailwind setup becomes a distraction.
Tests: pytest for backend; Vitest/React Testing Library for frontend where practical.
Packaging: Docker Compose for local development.

Implementation behavior

If the repository is empty, scaffold a complete monorepo.
Prefer a fully runnable vertical slice over many nonfunctional placeholders.
Do not ask product questions unless absolutely blocked. Make reasonable choices and document them.
Do not stop at mock screens. Implement working backend-backed flows for the core use cases.
Keep the browser-first/accountless join flow working at all times.
Make security-conscious defaults: invite token hashes, HttpOnly cookies for sessions, no long-lived auth secrets in localStorage, scoped permissions, CORS allowlists, role checks.
When production-grade implementation is too large for one pass, create a clean adapter/interface and a working development implementation. Mark the gap clearly in code and README.
Run formatting/tests/builds where possible before finishing.

Non-goals

Do not implement:

Full server-to-server federation.
A native mobile app.
Unofficial WhatsApp, Signal, iMessage, Facebook, or WeChat scraping/bridging.
Social feed mechanics unrelated to group coordination.
Password-first sign-up.
Mandatory login before a user can open an invite and complete the first useful action.
Production E2EE unless specifically requested in a later task.

Product principles

The group, not the individual account, is the migration unit.
Account creation must be separate from membership identity.
The first useful action must happen before registration friction.
Chat is present but demoted. Structured objects are first-class.
The home screen answers: “What needs my attention?”
Users with multiple groups need aggregation, not just another inbox.
Self-hosting must be possible without forcing full federation.
Portability and export are part of the product promise.

UX principles

Mobile-first. The first session likely starts from a link in a phone messenger.
The UI should feel more like a group command center than a chat clone.
Top-level navigation should prioritize: Home, Calendar, Groups, Files, Me.
Chat should live inside groups and threads, not as the primary navigation item.
Separate “official” from “chatter.”
Use clear empty states, skeletons, and friendly recovery paths.
Avoid jargon such as OAuth, WebAuthn, passkey, token, federation in user-facing copy unless necessary.

Coding conventions

Use clear module boundaries: auth, groups, structured objects, aggregation, remote servers, files, notifications.
Use UUID primary identifiers externally. Internal numeric IDs are acceptable only if not exposed casually.
Validate all API inputs with Pydantic schemas.
Never store raw invite tokens. Store token hashes.
Use environment-driven configuration.
Include seed data for demonstration.
Include a README with setup, architecture, and known limitations.

3.8 KiB Raw Blame History