fluncle

Fluncle

Drum & bass bangers from another dimension.

Fluncle discovers and certifies drum & bass bangers, logs each as a finding, and keeps the full archive across the Galaxy, with fluncle.com as home base.

Public Surfaces

The same archive, reachable however you like. Every surface reads the same public API and shares the same Log IDs.

| Surface | Where | What | | ---------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Web | <https://www.fluncle.com | The public archive: cover-led, dark, fast. Also /about, /log, /log/<id | | Galaxy | <https://galaxy.fluncle.com | The game: every finding is a star you can fly to | | Radio | <https://radio.fluncle.com | The cycling station: each finding's clean footage under its spoken observation, lean-back, forever | | Public API | https://www.fluncle.com/api/v1/ | JSON reads and submissions; the bare /api/ answers only for the file-route carve-outs (see Web, Submission Flow) | | RSS | <https://www.fluncle.com/rss.xml | The 25 most recent findings, for feed readers | | CLI | curl -fsSL https://www.fluncle.com/cli/latest.sh \| sh | The archive in your terminal (see CLI) | | DNS | dig random.dig.fluncle.com TXT +short | Findings answered over DNS TXT — latest, random, or any Log ID (see docs/dig.md) | | SSH | ssh rave.fluncle.com | The rave terminal, a Wish/Bubble Tea app (see SSH) | | MCP | https://www.fluncle.com/mcp | The archive as agent tools, Streamable HTTP, no auth (see MCP) | | Tor | http://p53pc2uzfu2tnih4cd6wd42ok6zup2uttj6xdmjdccy5kqo33fyppkqd.onion | The whole site mirrored onto Tor, off the grid: the archive plus the API, RSS, and MCP (see docs/tor.md) |

Crawler and discovery surfaces (all under <https://www.fluncle.com): /robots.txt, /sitemap.xml, /llms.txt, /llms-full.txt (the whole archive in one doc), /openapi.json, /.well-known/api-catalog, /.well-known/agent-skills/index.json, and /.well-known/mcp/server-card.json. Public pages also carry schema.org JSON-LD (WebSite, MusicPlaylist, MusicGroup, FAQPage, and per-finding MusicRecording with the Log ID).

Monorepo Layout

apps/cli              Bun/TypeScript CLI. Thin client for public reads and admin API calls.
apps/dns              Go DNS server behind dig.fluncle.com — findings answered over DNS TXT (docs/dig.md).
apps/extension        Fluncle Lens, an MV3 Chrome extension. Linkifies fluncle:// coordinates on any page.
apps/mobile           Expo React Native app (feed-first Stories + push). Thin client of the public API.
apps/raycast          Raycast extension. Thin client that shells out to the CLI.
apps/sonar            Rust in-memory exact-SIMD vector search engine — the whole MuQ corpus in RAM (docs/vector-serving.md).
apps/ssh              Go Wish/Bubble Tea SSH terminal behind ssh rave.fluncle.com. Thin client of the public API.
apps/web              TanStack Start public web app and server-side Fluncle API.
packages/contracts    oRPC contracts for the public + admin HTTP API (the contract-first surface).
packages/live         The live runtime: the glass (WebGL renderer) + the bridge (plan + fingerprint identity + supervisor + phone remote).
packages/media        Remotion kit for static image assets (link-preview cards, covers).
packages/registry     The typed catalog of every Fluncle surface (@fluncle/registry, the source of truth).

packages/sprites Fluncle's pixel-sprite family — the Galaxy game's sprites. Owns the PNGs; the web build mirrors them into public/. packages/test-support Shared test helpers — the no-network rail and the test preload. packages/tokens Shared design tokens (colors, typography, radii, motion) from DESIGN.md. packages/ui Shared @fluncle/ui design system: the Shadcn base + the Nostalgic Cosmos tokens, consumed by apps/web. packages/video Remotion kit for per-track social videos (the Nostalgic Cosmos).

The deployed web app owns the Spotify, Telegram, Turso, and Resend secrets. Every API route is served canonically under `/api/v1/*`. oRPC contract ops — the default for a public or admin HTTP surface — answer at that single prefix only; a bare `/api/*` contract path falls through to the router as a 404. The bare `/api/*` path survives solely for the file-route carve-outs (auth/OAuth redirects, large-body/streaming/media routes, non-JSON emitters), which keep it as a back-compat alias: the same handler object mounted at both paths, not a redirect, so POST bodies survive. Public reads are served by `/api/v1/tracks` (with `since`/`until` discovery windows), `/api/v1/tracks/random`, and `/rss.xml`. Newsletter signups post to `/api/v1/newsletter`, which the web app relays to Resend. The mobile app registers for push via `/api/v1/devices` (`register_device` / `deregister_device`); the web app then relays a notification to the Expo Push Service when a finding or mixtape publishes — best-effort and a no-op until `EXPO_ACCESS_TOKEN` is set, like the Telegram/Last.fm side-channels. Admin mutations are served by authenticated `/api/v1/admin/*` routes. Raycast must keep calling `fluncle`.
Listener submissions are accepted through public `/api/v1/search` and `/api/v1/submissions` routes, then reviewed through authenticated admin submission routes. Approval still publishes only through the existing admin add flow. Optional web accounts are private overlays on the same Log ID spine: signed-in listeners can sync Galaxy lifetime progress, save findings, see their own submissions, export data, and delete the account without changing anonymous Fluncle.

## Private Companion

Some operator-only material is deliberately not in this repo — exact runtime recipes, the concrete secret/topology map, local-dev support, and work that is not part of the product. It lives in a private companion repo, `fluncle-labs`.

**This repo is self-contained:** nothing here needs the companion to build, run, test, or deploy. The split is about what should be world-readable, not about hiding a dependency. If you have access, its README states the boundary; if you do not, nothing here requires it.

## License

The Fluncle name, logo, visual identity, social/profile artwork, generated media assets, track curation data, playlist identity, and other brand assets are not licensed for reuse except where explicitly stated.

Root Workflows

bun install
bun run dev
bun run build
bun run typecheck
bun run lint
bun run lint:fix
bun run format
bun run format:check
bun run check
bun run check:fix

Root scripts are orchestrated with Turborepo. oxlint and oxfmt run from the root with workspace-aware configs. apps/raycast is the exception: Raycast's CLI owns extension formatting, and ray lint runs its own Prettier check over src/.

Environment

Fluncle now has two env surfaces:

• Operator machines: optional ~/.config/fluncle/.env.production for production CLI admin commands and ~/.config/fluncle/.env.local for local development.
• Web/API: Wrangler secrets in production, and a local apps/web/.dev.vars rendered from apps/web/.dev.vars.tpl with 1Password for local Worker previews.