Docs

Architecture

Focussstody is a vanilla JS ES-module app — no bundler, no framework. Pages are plain HTML files that import JS modules directly. Backend is entirely Supabase (Postgres + Auth + Realtime).

Tables

profiles

id          uuid  PK  (= auth.users.id)
username    text  UNIQUE
email       text
is_pro      bool  DEFAULT false

study_data

user_id         uuid  FK → profiles.id
sessions        jsonb   -- { "CODING": 3600, "MATH": 1800 }
total_exp       int
weekly_log      jsonb   -- { "2026-05-01": 3600 }
streak          int
last_study_date date
goal_hours      jsonb   -- { "CODING": 4 }
notes           jsonb   -- [{ date, subject, text, duration }]
store_items     jsonb   -- ["midnight", "galaxy_brain"]
active_theme    text
updated_at      timestamptz

daily_challenges

id      uuid  PK
date    date  UNIQUE
type    text  -- 'study_time' | 'sessions' | 'streak'
target  int
reward  int   -- XP bonus

challenge_completions

user_id       uuid  FK → profiles.id
challenge_id  uuid  FK → daily_challenges.id
PRIMARY KEY (user_id, challenge_id)

StudyTimer timer.js

Pure timing logic — no DOM. Receives callbacks, returns data.

const timer = new StudyTimer(
    (data) => render(data),   // onTick — fires every second
    (payload) => save(payload) // onSave — fires on pause/note/reset
);

timer.loadFromDB(row);        // hydrate from Supabase row
timer.start('CODING');        // begin session
timer.pause();                // stop + save delta
timer.addNote(subject, text, duration);
timer.reset();                // wipe all data

timer.getStats();             // → { sessions, total_exp, rank, weeklyData, … }
timer.getRank(exp);           // → { name, level, next, prev }
timer.getGoal(subject);       // → number (hours)
timer.setGoal(subject, hours);

The onTick callback receives { formatted, raw, rawTotalExp, progress, rank } every second. raw is current subject seconds; rawTotalExp is live total (not yet persisted).

Authentication supabase.js · authcheck.js

All auth flows live in supabase.js. Multi-page apps use requireAuth() from authcheck.js as a guard at the top of each page script.

// supabase.js exports
signUp(username, email, password)
signIn(username, password)   // looks up email by username first
signOut()
getSession()                  // reads localStorage — no network

// authcheck.js
import { requireAuth } from './authcheck.js';
const { supabase, userId, username, profile, studyRow }
    = await requireAuth();
// → redirects to login.html if no session

ProManager & Themes pro.js

Handles Pro status, theme switching, and CSV export.

import { ProManager, THEMES } from './pro.js';
const pro = new ProManager();

pro.isPro                     // bool
await pro.unlock(code)        // → true/false
pro.applyTheme(key, ownedItems) // sets CSS vars on :root
pro.restoreTheme(ownedItems)  // call on page load
pro.exportCSV(timerStats, username)

THEMES is a plain object keyed by theme ID. Each entry has: accent, accentDim, bgLight, bgFocus, textPrimary, miningFrom, miningTo, free.

To add a new theme, add an entry to THEMES in pro.js and a matching gradient in the gradients map inside buildThemeGrid() in app.js.

StoreManager store.js

Manages purchases stored in localStorage (keyed per username) and synced to Supabase's store_items column.

const store = new StoreManager(username);

store.owns(itemId)             // → bool
store.buy(id, price, tokens, isPro)
     // → { ok: true, cost } | { ok: false, reason }
store.setActiveSound(soundId)
store.setActiveBadge(badgeId)
store.playTickSound()          // plays active sound each second

To add a catalog item, push to STORE_ITEMS.themes, .badges, or .sounds in store.js. Each item needs { id, name, price, proFree, emoji } — plus preview (two hex colours) for themes.

StudyRoom — Realtime Presence room.js

Uses Supabase Realtime presence channels. Each user tracks { username, subject, startedAt }.

const room = new StudyRoom(username, (users) => render(users));

await room.join();             // subscribe to channel
await room.startStudying(subject); // track presence
await room.stopStudying();     // untrack
await room.leave();            // unsubscribe

The onUpdate callback receives an array of { username, subject, startedAt, isMe } sorted by join time.

PomodoroManager pomodoro.js

Self-contained — no Supabase. Settings saved to localStorage under fv_pomodoro.

const pomo = new PomodoroManager();

pomo.saveSettings(focusMin, breakMin);
pomo.start(onTick, onPhaseSwitch);
// onTick → { formatted, remaining, phase, pomosToday }
// onPhaseSwitch → 'focus' | 'break'

pomo.pause();
pomo.stop();
pomo.isRunning  // bool
pomo.phase      // 'focus' | 'break'
pomo.settings   // { focusMin, breakMin }

ChallengeManager challenges.js

const cm = new ChallengeManager(userId, (reward) => {
    // called on successful claim
});

await cm.load()               // → { challenge, completed }
cm.getProgress(studyData)     // → 0–1
cm.isClaimable(studyData)     // → bool
await cm.claim()              // → bool

Challenges are seeded in the daily_challenges table. The manager uses challenge_completions to prevent double-claiming. Token award falls back to a direct UPDATE if the increment_exp RPC isn't available.

SlidingTabs sliding-tabs.js

Universal animated pill-tab component. Works on any container with <button> children.

import { SlidingTabs } from './sliding-tabs.js';

const tabs = new SlidingTabs(trackEl, (index, btn) => {
    // called when tab changes
});

tabs.select(index);   // programmatically switch
tabs.refresh();       // recalculate pill if layout changes

PWA Setup sw.js

Focussstody is a PWA — installable on mobile and desktop. The service worker caches core assets for offline use via a cache-first strategy.

• Cache name: focussstody-v1 — bump the version string in sw.js to force a cache refresh on deploy.
• The ASSETS array lists files that are pre-cached on install. Add new pages/scripts there.
• Dynamic fetches fall through to the network if not cached.

CSS Variables Reference

All theme values are written to :root by ProManager.applyTheme(). Use these in any page or component:

--accent        /* primary accent colour */
--accent-dim    /* accent at ~40% opacity */
--text-primary  /* dark foreground for light backgrounds */
--bg-light      /* page background colour */
--bg-focus      /* used in the mining/timer card gradient */
--dropdown-bg   /* context-aware dropdown background */

The global --bg, --ink, --ink2, --glass, --border variables are set in each page's own CSS and flip via the html.dark class. Dark mode state is persisted in localStorage under darkMode.

Reporting Bugs / Suggestions

DM @focussstody_official on Instagram. Bugs get fixed fast; good suggestions get built.