Focusbeacon

Focusmate session statistics & productivity dashboard

View demo · Bug report · Feature request

Technologies

Backend

• Python for data processing
• FastAPI for the REST API
• Supabase for the PostgreSQL database
• Vercel for hosting
• PostHog for logging

Frontend

• TypeScript for type safety
• React.js for the UI
• Next.js App Router for routing
• TailwindCSS for styling

For authentication, we use the Backend for Frontend pattern with Focusmate as the identity provider via OAuth 2.0. Focusbeacon is the first and only non-commercial app to be approved by Focusmate for this purpose!

Getting started locally

1. Clone this repo to your local machine

git clone https://github.com/qu8n/focusbeacon.git

2. Navigate to the project directory

cd focusbeacon

3. Ensure the following language versions are used in your local environment:

• Node.js (v22.12 or newer)
• Python (v3.12)

4. Install packages with npm

npm install

5. Create a Python virtual environment

python3 -m venv venv

6. Install Python dependencies

pip install -r requirements.txt

7. Create an .env file in the root directory following the .env.example template and fill in the required values

cp .env.example .env

8. Activate the Python virtual environment

source venv/bin/activate

9. Run the app in development mode. This command will start the FastAPI server and the Next.js server concurrently

npm run dev

Running the tests

npm test          # Vitest: lib, hooks, components, route handlers, middleware
npm run test:py   # pytest: the FastAPI routes and everything under api_utils
npm run test:e2e  # Playwright: demo-mode smoke tests in a real browser
npm run typecheck # tsc --noEmit

None of these need credentials. The Python tests set their own fake environment before importing anything, and the Playwright suite runs entirely against ?demo=true, which reads a static fixture in the browser — so no OAuth, no Supabase and no serverless function is involved.

Playwright needs its browser once:

npx playwright install chromium

Two further checks guard the demo dashboard, which is served from a committed fixture that can drift from the API it was generated from:

npm run check:demo   # regenerate the fixture and replay it against the API

The pre-push hook runs pytest, Vitest and check:demo — about five seconds. GitHub Actions runs all of it, plus lint, typecheck and Playwright, on every push and pull request.

Update Supabase types using the CLI

Initialize a local Supabase project: (only needs to be done once)

npx supabase login
npx supabase init

This will create a supabase directory in your project.

Automatically generate TypeScript types for your Supabase tables:

npm run supabase-typegen

Note that this script only works on Linux/MacOS because of the way it accesses .env file.

Contributing

By default, contributors will not have access to the Focusmate OAuth login nor production database. If your contributions require access to these, please reach out to me here. Meanwhile, you can still use the demo view to test your changes.

If you have a suggestion that would make this better, feel free to fork the repo and create a pull request. I'm also happy to chat over a Focusmate session to get you started with the codebase.