zzstoatzz.io
+1
-2
.gitignore
+1
-2
.gitignore
+49
AGENTS.md
+49
AGENTS.md
···
1
+
# plyr.fm Developer Context
2
+
3
+
**music streaming on AT Protocol**
4
+
5
+
## 🚨 Critical Rules & Workflows
6
+
* **Read `STATUS.md` First:** Always check for active tasks and known issues.
7
+
* **Workflow:**
8
+
* Use **GitHub Issues** (not Linear).
9
+
* **PRs:** Always create for review; never push to main directly.
10
+
* **Deploy:** Automated via Actions (Backend: Fly.io, Frontend: Cloudflare Pages). Never deploy locally.
11
+
* **ATProto Namespaces:** namespaces are environment-aware via settings (e.g., `fm.plyr.dev`, `fm.plyr`). **Never** hardcode outside of scripts
12
+
* **Auth Security:** Session IDs live in HttpOnly cookies. **Never** touch `localStorage` for auth.
13
+
* **Async Everywhere:** Never block the event loop. Use `anyio`/`aiofiles`.
14
+
* **Type Hints:** Required everywhere (Python & TypeScript).
15
+
* **Communication:** Use emojis sparingly and strictly for emphasis.
16
+
17
+
## 🛠️ Stack & Tooling
18
+
* **Backend:** FastAPI, Neon (Postgres), Cloudflare R2, Fly.io.
19
+
* **Frontend:** SvelteKit (Svelte 5 Runes), Bun, Cloudflare Pages.
20
+
* **Observability:** Logfire.
21
+
* **`just` use the justfile!
22
+
* **use MCPs for access to external systems, review docs/tools when needed
23
+
24
+
## 💻 Development Commands
25
+
* **Setup:** `uv sync && just frontend install`
26
+
* **Backend:** `just run-backend` (or `uv run uvicorn backend.main:app --reload`)
27
+
* **Frontend:** `just frontend dev` (or `cd frontend && bun run dev`)
28
+
* **Tests:** `just test`
29
+
* **Linting:** `just lint`
30
+
* **Migrations:** `just migrate "message"` (create), `just migrate-up` (apply)
31
+
32
+
## 📂 Project Structure
33
+
```
34
+
plyr/
35
+
├── src/backend/
36
+
│ ├── api/ # Public endpoints
37
+
│ ├── _internal/ # Auth, PDS, Uploads logic
38
+
│ ├── models/ # SQLAlchemy schemas
39
+
│ ├── storage/ # R2 and filesystem adapters
40
+
│ └── utilities/ # Config, helpers
41
+
├── frontend/ # SvelteKit app
42
+
│ ├── src/routes/ # Pages (+page.svelte, +page.server.ts)
43
+
│ └── src/lib/ # Components & State (.svelte.ts)
44
+
├── scripts/ # Admin scripts (uv run scripts/...)
45
+
├── docs/ # Architecture & Guides
46
+
└── STATUS.md # Living status document (Untracked)
47
+
```
48
+
49
+
this file ("AGENTS.md") is symlinked to `CLAUDE.md` and `GEMINI.md` for maximal compatibility.
+1
-37
CLAUDE.md
+1
-37
CLAUDE.md
···
1
-
# plyr
2
-
3
-
we're building a music streaming platform on ATProto.
4
-
5
-
## critical reminders
6
-
7
-
REMEMBER WE HAVE THE @justfile
8
-
9
-
- **issues**: GitHub, not Linear
10
-
- **PRs**: always create for review before merging to main
11
-
- **deployment**: automated via GitHub Actions on merge - NEVER deploy locally
12
-
- **migrations**: automated via fly.io release_command
13
-
- **logs**: `flyctl logs` is BLOCKING - use `run_in_background=true`
14
-
- **type hints**: required everywhere
15
-
- **ATProto namespaces**: NEVER use Bluesky lexicons (app.bsky.*). ALWAYS use our namespace (fm.plyr.*), configured per environment via `ATPROTO_APP_NAMESPACE` (e.g., fm.plyr.dev for dev, fm.plyr for prod)
16
-
- **communication**: use emojis sparingly and strictly for emphasis (avoid excessive check marks)
17
-
18
-
## structure
19
-
20
-
```
21
-
plyr/
22
-
├── src/backend/
23
-
│ ├── api/ # public endpoints (see api/CLAUDE.md)
24
-
│ ├── _internal/ # internal services (see _internal/CLAUDE.md)
25
-
│ ├── models/ # database schemas
26
-
│ ├── storage/ # R2 and filesystem
27
-
│ └── utilities/ # helpers, config, hashing
28
-
├── frontend/ # SvelteKit (see frontend/CLAUDE.md)
29
-
├── tests/ # test suite (see tests/CLAUDE.md)
30
-
└── docs/ # organized guides (see docs/CLAUDE.md)
31
-
```
32
-
33
-
## development
34
-
35
-
backend: `uv run uvicorn backend.main:app --reload`
36
-
frontend: `cd frontend && bun run dev`
37
-
tests: `just test`
1
+
AGENTS.md
+1
GEMINI.md
+1
GEMINI.md
···
1
+
AGENTS.md