# BRETT

An imageboard-style upload and discussion platform built with **Nuxt 4** and **shadcn-vue**. Users can upload files or URLs, comment in threads (including file attachments and voice messages), respond with Discord-style reactions, subscribe to threads, and pick from over 20 themes.

## Features

- **Uploads:** Drag & drop (page dropzone + upload popover), file or URL upload, max. 200 MB. Types: **images** (generated thumbnails), **videos** (embedded Plyr player), **audio** (MP3/FLAC with embedded cover art and music metadata via `music-metadata`, dedicated player dialog), **YouTube** and **Twitch embeds**, plus **link preview cards**
- **Threads & comments:** Every upload is a thread with comments. Comments support **file attachments** and **voice messages** recorded in the browser (converted to MP3 via `ffmpeg-static`). Discord-style **reactions** on both comments *and* uploads (toggle, counters, tooltips, optimistic updates, burst animation), **@mentions** with autocomplete suggestions and profile hover cards — all with **live WebSocket updates**
- **Thread subscriptions & notifications:** Creating, commenting, favoriting, or reacting to a thread automatically subscribes you (`thread_subscriptions` table). Can be toggled per thread via a bell button (a disabled subscription stays disabled even on later participation and also suppresses mentions in that thread). Notifications are **grouped per thread** (no spam from multiple comments), there are **no self-notifications**, and the bell shows live events plus toasts
- **Announcement (MOTD):** Admin-editable slim bar below the header (`MotdBanner.vue`), publicly readable and updated live via WebSocket
- **Tags & filters:** Uploads can be tagged; filter popover by **type, uploader, time range, and tag** (URL query–driven)
- **Command palette:** `Ctrl/Cmd + K` opens a global search across uploads/users/actions
- **Favorites:** Favorite uploads, visible on the profile page
- **Auth & roles:** Session-cookie login (30 days); the first registered user automatically becomes admin. **Admin panel** with user list, role management, and **per-role configurable permissions** (`admin.access`, `roles.manage`, `users.manage`, `site.manage`, `comment.delete`, `upload.delete`, `tag.delete`) — the `admin` role is an implicit wildcard and can do everything; `moderator` is a system role with moderation rights
- **Profiles & personalization:** Profile pages with own uploads, comments, and stats; user overview page. In settings: **avatar** (max. 5 MB), **name color**, **card effects** (WebGL shaders via `ogl` — Aurora, Particles, Plasma, Silk, Dither, Scanner and more as hover-card backgrounds), **border effects**, and vignette
- **Themes:** 21 themes (Standard, Discord, Cyberpunk, Spring, Terminal, Infoseer, Homebrew, Florense, Kawi Green, Clo.nz, Clawmorphism, Realmorphism, Amber, Sunny Sprout, Spotify, Nordic Theme, SS, Amethyst Haze, Deep Wine, myClaude, Neo), switched via `data-theme` on `<html>`, persisted via cookie — SSR-safe without flash. The imported TweakCN themes are included as dark variants only
- **Layouts:** Switchable Bento/uniform grid for the upload overview

## Tech stack

| Area | Technology |
|---|---|
| Framework | Nuxt 4 / Nitro, Vue 3 (`<script setup>` + TS) |
| UI | shadcn-vue (`shadcn-nuxt`), Reka UI, Tailwind CSS v4, Phosphor/Simple Icons via `@nuxt/icon` (local SVG bundle mode), vue-sonner |
| Database | MariaDB 11 + Drizzle ORM (`mysql2`) |
| Realtime | Nitro WebSocket (`crossws`) |
| Media | `@nuxt/image`, Plyr, `music-metadata`, `ffmpeg-static`, `ogl` (shader effects) |
| Data/Utils | `@tanstack/vue-table`, Zod, Unovis charts, dnd-kit-vue |
| State | Nuxt `useState` composables, VueUse |

## Project structure

```
app/
  assets/css/tailwind.css   # Tailwind v4 entry + all theme tokens ([data-theme="…"])
  components/               # App components (header, dropzone, tiles, comments,
                            #   MotdBanner, CommandPalette, ThreadSubscriptionButton, …)
    effects/                # WebGL card effects + vignette/border
    ui/                     # shadcn-vue base components
  composables/              # useAuth, useTheme, useCommandPalette, useCommentReactions,
                            #   useNotifications, useCardShader, …
  layouts/ middleware/ plugins/ pages/
    index.vue               # Upload grid with filters / homepage
    thread/[id].vue         # Thread detail page with comments, attachments, voice recording
    admin.vue               # Admin panel (users, roles, permissions, MOTD)
    settings.vue            # Profile settings (avatar, color, card effects)
    users.vue user/[id].vue login.vue register.vue
server/
  api/                      # Nitro endpoints (auth, uploads, comments, notifications,
                            #   users, tags, link-preview, motd, admin/…)
  db/schema.ts              # Drizzle schema (users, sessions, uploads, comments,
                            #   comment_attachments, comment_reactions,
                            #   upload_reactions, favorites, thread_subscriptions,
                            #   link_previews, notifications, roles, user_roles,
                            #   permissions, role_permissions, tags, upload_tags,
                            #   settings)
  db/migrations/            # Generated SQL migrations
  plugins/migrate.ts        # Runs migrations on server start (dev)
  routes/_ws.ts             # WebSocket route for live events (broadcastToAll)
  utils/                    # auth (requirePermission), db, roles, uploads,
                            #   notifications, threadSubscriptions, linkPreview
scripts/migrate.ts          # Manual migration runner (npm run db:migrate)
shared/utils/               # Shared utilities — incl. permissions.ts (catalog + seeding)
public/uploads/             # Upload target, incl. uploads/avatars/ (gitignored)
docker-compose.yml          # MariaDB container
```

## Setup

**Requirements:** Node.js ≥ 20, Docker (for the bundled MariaDB) or your own MySQL/MariaDB instance.

```bash
# 1. Start the database
docker compose up -d

# 2. Configure environment
cp .env.example .env   # contains DATABASE_URL, matches the Docker setup

# 3. Install dependencies
npm install

# 4. Fetch the ffmpeg binary (needed for voice messages → MP3;
#    the download runs in ffmpeg-static's postinstall script, which may be
#    blocked depending on your npm configuration)
node node_modules/ffmpeg-static/install.js

# 5. Start the dev server (migrations + permission seeding run automatically)
npm run dev
```

The app runs on <http://localhost:3000>. The **first registered account automatically gets the admin role** and can then create additional roles, assign permissions, and set the announcement in the admin panel.

### Without Docker

Provide your own MariaDB/MySQL instance and adjust `DATABASE_URL` in `.env`:

```
DATABASE_URL=mysql://user:pass@host:3306/database
```

## NPM scripts

| Command | Purpose |
|---|---|
| `npm run dev` | Dev server with HMR, auto-migrations |
| `npm run build` | Production build |
| `npm run preview` | Run the built app locally |
| `npm run db:generate` | Generate a new Drizzle migration from a schema change |
| `npm run db:migrate` | Apply migrations manually |
| `npm run db:studio` | Drizzle Studio (DB GUI) |

## Development

- **Change the schema:** Edit `server/db/schema.ts` → `npm run db:generate` → commit the migration. In dev mode, `server/plugins/migrate.ts` applies it automatically on start.
- **Add a new permission:** Add an entry to `PERMISSIONS` in `shared/utils/permissions.ts` → seeded on next start via `seedPermissions()`; check server-side with `requirePermission(event, key)`, client-side with `can(key)` from `useAuth`.
- **Live events:** The server broadcasts via `broadcastToAll` in `server/routes/_ws.ts`; the client handles events in `app/plugins/notifications.client.ts`.
- **Add a new theme:** Create a `[data-theme="…"]` block with the CSS variables in `app/assets/css/tailwind.css`, add the name to `THEME_NAMES` in `app/composables/useTheme.ts`, and add an entry in `app/components/ThemeSelector.vue`. Themes can also override the `shadow-*` tokens (glow, offset, or flat shadows) and `font-sans`/`font-heading`/`font-mono`; `--font-logo` intentionally stays theme-independent.
- **Conventions:** Semantic tokens instead of hardcoded colors (`primary`, `accent`, `muted`, …); `rounded-md`/`rounded-sm` scale via `--radius` with the theme (`neo` is square: `--radius: 0`). More details in `AGENTS.md`.
- **Health check:** `GET /api/health` reports the DB connection status.