72 lines
3.8 KiB
Markdown
72 lines
3.8 KiB
Markdown
# 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
|
|
|
|
1. The group, not the individual account, is the migration unit.
|
|
2. Account creation must be separate from membership identity.
|
|
3. The first useful action must happen before registration friction.
|
|
4. Chat is present but demoted. Structured objects are first-class.
|
|
5. The home screen answers: “What needs my attention?”
|
|
6. Users with multiple groups need aggregation, not just another inbox.
|
|
7. Self-hosting must be possible without forcing full federation.
|
|
8. 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.
|