Namek

Event badge scanner. Holds up a name badge → OCR reads the name → an animated 3D theme of that name plays over a background video. Optional second monitor as a player.

Stack: Wails v2 (Go backend) + Svelte/TypeScript (frontend) + Three.js (3D text) + bundled OCR sidecars (Tesseract, PaddleOCR).

Read mvp.md for the ordered build phases. This file is the canonical repo layout and operating rules.

Repo layout

namek-app/
├── main.go                       # Wails entry. Flags: --player, --connect=ws://...
├── app.go                        # App struct (Wails Bind target)
├── wails.json                    # Wails project config (version, build hooks)
├── VERSION                       # Single source of truth for product version
├── internal/                     # Go backend, not exposed to Svelte directly
│   ├── capture/                  # Camera enumeration + GrabFrame() + lock state machine
│   ├── stillness/                # SSIM / grayscale-diff frame stillness detector
│   ├── ringbuffer/               # 10-slot in-memory frame buffer
│   ├── ocr/                      # Tesseract / Paddle / consensus + SQLite debug log
│   ├── ner/                      # Name extraction: regex + bundled name dict
│   ├── playlist/                 # Video playlist load/save (config/playlist.json)
│   ├── themes/                   # Persisted enabledIds + per-theme overrides
│   └── ipc/                      # In-process bus + ws bridge for player windows
├── frontend/
│   ├── src/
│   │   ├── routes/
│   │   │   ├── +page.svelte      # Scanner (default)
│   │   │   └── player/+page.svelte  # --player route: Stage only
│   │   └── lib/
│   │       ├── stage/            # VideoDeck, Stage, TextStage (Three.js)
│   │       ├── stores/           # playlist, debug, theme stores
│   │       ├── themes/           # _base.ts (TextSceneModule), registry, theme files
│   │       ├── konami/           # listener.ts (Ctrl+Shift+\ admin toggle)
│   │       └── components/       # CameraPanel, TextScenesModal, VideoScenesModal, etc.
│   └── (Wails-generated config)
├── assets/
│   ├── videos/                   # Default background loops
│   ├── fonts/                    # facetype JSON for Three.js text
│   └── images/                   # Ghost-card outlines, icons
├── config/                       # Runtime config (committed: .gitkeep only)
├── bin/                          # tesseract.exe, paddleocr.exe (fetched, not committed)
├── installer/
│   └── nsis/                     # NSIS installer script
├── web/                          # The namek.top site. `just site-deploy` syncs to /var/www/namek/
│   ├── index.html
│   ├── changelog.md              # Embedded into site at build time
│   └── (assets)
├── scripts/                      # Dev helper scripts
├── dist/                         # Build output: namek.exe, Namek-Setup-X.Y.Z.exe
├── justfile
├── .gitignore
├── README.md                     # This file
└── mvp.md                        # Build plan / phase tracker

TextSceneModule interface

Every theme in frontend/src/lib/themes/ exports this:

export interface TextSceneModule {
  id: string;                                  // unique, kebab-case
  label: string;                               // human-readable name
  optionsSchema?: OptionsSchema;               // drives the admin editor UI
  defaultDurationMs: number;                   // how long the lock animation plays
  init(ctx: SceneContext, opts: object): SceneInstance;
}

export interface SceneInstance {
  update(deltaMs: number): void;
  cleanup(): void;
}

export interface SceneContext {
  scene: THREE.Scene;
  camera: THREE.Camera;
  renderer: THREE.WebGLRenderer;
  text: string;                                // the locked name
  font: THREE.Font;                            // pre-loaded face
}

The registry (frontend/src/lib/themes/registry.ts) discovers theme modules via a Vite import.meta.glob, holds enabledIds, and pickNext(name) returns the next theme with no-repeat-until-cycle-exhausted shuffle.

Just commands

$NAMEK_SITE_DEST defaults to /var/www/namek/ on the deploy box.

Hard rules (from mvp.md — repeated here so they're never missed)

• No runtime network calls other than 127.0.0.1.
• Camera frames never touch disk outside the debug-only OCR SQLite log.
• No binaries >50MB committed without owner approval — just fetch-deps pulls them.
• No new top-level folders beyond what's listed above.
• Files ≤150 lines, functions ≤30 lines wherever practical.
• Phase boundaries are real — finish a phase before refactoring across them.
• Scope creep → QUESTIONS.md — don't guess; surface and stop.

Daily working rhythm

1. Pull. Read mvp.md and find the active phase's first unchecked task.
2. Make the smallest commit that advances it.
3. Tick the checkbox in mvp.md in the same commit.
4. If a task surfaces a scope question → write it into QUESTIONS.md and stop.

Owner

[email protected] — GitHub saintpetejackboy. Repo: https://github.com/saintpetejackboy/namek-app (private). Deploys to: https://namek.top.