TECHNICAL CASE STUDY
A dedicated RetroAchievements dashboard running on a Raspberry Pi display.
My brother and I compete for high scores on RetroAchievements. I wanted a way to keep track of what he was playing, how our scores were changing, and who was gaining ground each week without constantly checking the site.
LeftoverAchievements turns that idea into a dedicated Raspberry Pi display with a local dashboard, live achievement updates, historical tracking, rankings, and an update system that helps it behave more like an appliance than a normal computer.
Also packaged for macOS and Windows.
FULLSCREEN DISPLAY
LIVE INTERFACE
OVERVIEW
LeftoverAchievements was always meant to be something physical. The Raspberry Pi runs the backend, stores local state, talks to RetroAchievements, and drives a fullscreen Chromium display. The same application serves a LAN dashboard for setup, administration, charts, history, and player management.
The display rotates through overall and weekly rankings, current games, and recent activity, then interrupts that cycle when somebody earns an achievement, beats a game, or reaches mastery. Later, I expanded the same system into packaged desktop runtimes for notifications and a dedicated window.
The intended boundary is a trusted LAN. The dashboard is not designed as an authenticated, TLS-terminated internet service.
FULL LAN DASHBOARD
LIVE INTERFACE
SYSTEM STRUCTURE
I kept the core as one FastAPI application. It handles polling, storage, the server-rendered admin screens, JSON APIs, and the display event stream. There is no SPA framework or network of microservices to coordinate.
Jinja renders the dashboard, plain JavaScript handles interaction, and a vendored copy of Chart.js keeps the charts local. SQLite sits behind both the interactive views and the background work.
SYSTEM MAP
A modular monolith with two external boundaries
RASPBERRY PI APPLIANCE
The Pi does not boot into a normal desktop workflow. systemd starts the backend while LightDM independently enters a project-specific labwc session. Chromium launches in kiosk mode with its own browser profile, suppressed prompts, and a supervised restart loop.
The graphical session and backend do not always become ready at the same moment, so Chromium opens a small local loading page first. That page checks 127.0.0.1:8000 and moves to /display when the service responds. This lets the display and backend start separately without breaking startup.
BOOT SEQUENCE
Two startup paths meet at readiness
PI BOOT
Raspberry Pi OS starts normally
SYSTEMD
Starts the FastAPI backend
LIGHTDM
Logs into a project-specific session
LABWC
Creates the private kiosk environment
CHROMIUM
Opens a local readiness page
/DISPLAY
Takes over when the backend responds
The readiness page absorbs the race between the service and graphical session; neither has to pretend the other starts synchronously.
LIVE DISPLAY
The passive display cycles through overall ranking, weekly ranking, current games, and recent activity. It was built for the current seven-inch appliance, but it is not locked to that screen: the layout responds to any browser or desktop-app window size and orientation, changing density, scale, and visible content as the viewport moves.
When polling detects an achievement, beaten game, or mastery, SSE pushes a local event that interrupts the carousel with a focused overlay and its configured sound. Individual slides can be replaced without reloading the entire display.
Touch controls let me jump to the information I want, pause the rotation, change its speed, adjust audio, or scale the interface without waiting for the timed cycle.
LIVE EVENT INTERRUPTS
LIVE INTERFACERESPONSIVE DISPLAY SYSTEM
LIVE INTERFACERETROACHIEVEMENTS DATA FLOW
RetroAchievements does not push these events to the application. LeftoverAchievements detects them by polling, so external requests are serialized and spaced at least 0.75 seconds apart. A 429 response respects Retry-After instead of immediately trying again.
Tracked users are distributed through polling slots. The achievement loop aims to cover everyone in roughly 60 seconds, while current activity covers all users inside its 75-second cache interval. Weekly rankings and other slower-changing data use different cache lifetimes.
Failures preserve useful cached data. On a fresh installation, the first successful pass records existing achievements as a baseline instead of replaying years of old unlocks as new live events.
POLLING PIPELINE
One controlled path from API to display
RETROACHIEVEMENTS
7 API endpoints
RATE-LIMITED POLLER
Serialized · ≥ 0.75s spacing
NORMALIZATION
Different cache lifetimes
SQLITE + CACHE
Useful data survives failures
DASHBOARD + SSE
Views and local live events
PLAYER MANAGEMENT
LIVE INTERFACE
LIVE EVENTS & RESTARTS
/display/events uses a long-lived SSE connection. That is useful while the display is running, but a persistent stream can delay Uvicorn shutdown during an update or service restart.
The launcher now sends a shared shutdown event before Uvicorn starts waiting. Each SSE stream watches its subscriber queue, that shutdown signal, and a heartbeat timeout. During shutdown it closes the stream and cancels outstanding waits. Chromium’s EventSource reconnects when the backend returns, while Uvicorn and systemd keep their timeout fallbacks.
RESTART LIFECYCLE
Close the stream, restart, reconnect
UPDATE OR RESTART
→SET SHUTDOWN EVENT
→SSE STREAM EXITS
→UVICORN RESTARTS
→EVENTSOURCE RECONNECTS
The display loses its connection briefly, but it does not need a coordinated page reload or a special recovery screen.
PROFILES & HISTORICAL DATA
The RetroAchievements API is the source, but I did not want to copy the entire site. Each player profile keeps the parts I care about together: current totals, recently played games, recent unlocks, preferred consoles and genres, mastered and beaten games, and a personal progression chart.
The shared charts answer questions that RetroAchievements does not surface. They compare tracked players’ weekly Hardcore Points and RetroPoints, preserve weekly rank history, and show group patterns such as achievements earned by day of the week or month.
The same history can be played in two ways. An all-time animation shows each player’s score and game milestones across the full history, while the monthly timeline moves through one month at a time.
Those views need more than one API response. The app requests achievement history in monthly ranges and stores each completed chunk, so interrupted work can resume. Weekly snapshots and group charts are then built from that shared history.
The reconstructed curves use dated unlocks and current point values, so they are not perfect historical snapshots. Removed achievements or past point-value changes cannot be reproduced exactly; the interface states that limitation instead of implying precision the source data cannot provide.
CONDENSED PLAYER PROFILE
LIVE INTERFACE
WEEKLY GROUP ANALYTICS
LIVE INTERFACE
WEEKLY SNAPSHOTS
LIVE INTERFACE
ALL-TIME PROGRESSION
LIVE INTERFACE
MONTHLY TIMELINE
LIVE INTERFACESAFE RELEASES & UPDATES
Publishing a GitHub Release starts platform builds. The application can detect that release, but it never installs it silently: the user chooses when to install. On the Pi, the package is downloaded and validated in staging before a new release-specific virtual environment is built.
Activation is one atomic symlink change. If the restart or a system migration fails, the symlink moves back to the previous version and that release is restarted. The database, configuration, audio, logs, and update status live outside the versioned release directories, so replacing application code does not replace user state.
The web application is not allowed to execute arbitrary commands as root. A root-owned helper exposes only the specific update and migration actions the release flow needs.
RELEASE FLOW
Validate first, move one pointer, keep a way back
GITHUB RELEASE
Versioned source and release metadata
↓PLATFORM BUILD
Actions creates the Pi package
↓USER APPROVAL
The app offers the release; the user chooses Install
↓STAGING
Download, inspect, validate, and build a new virtual environment
↓ATOMIC ACTIVATE
Move the current symlink to the new release
↓RESTART OR ROLLBACK
Restart the service, or restore the previous symlink
Validation covers package paths, version, architecture, size, and mutable-file exclusions before anything becomes current.
PERSISTENT DIRECTORY MODEL
~/.local/share/LeftoverAchievements/
app/
releases/vX.Y.Z/
current → releases/vX.Y.Z
data/
leftover.db
.env
instance-config.json
audio/
logs/
update-status
Versioned application code can move forward or back while mutable state remains in one stable location.
DEVICE ADMINISTRATION
LIVE INTERFACE
HUB / CLIENT MODE
I wanted to minimize duplicate API traffic, especially because RetroAchievements throttles requests. I also did not want every display to require the same setup again.
One installation can act as the hub: it owns the API credentials, polling, and shared data. Client frontends send their requests to that hub and stop their own local polling. A client’s existing SQLite database is retained rather than merged or destroyed, which keeps changing modes reversible.
This is meant for a trusted LAN, not the cloud. It cuts down repeated work across a few installations without adding a distributed backend.
LAN TOPOLOGY
One hub, several ways to look at it
HUB
API credentials + polling + shared data
DESKTOP EXPANSION
Once the core system was working, I realized much of it did not depend on the physical display. The same backend could surface native notifications or run in a dedicated desktop window.
Packaged runtimes now target macOS arm64, macOS x64, and Windows x64. One runtime check handles storage paths, ports, processor type, packaging behavior, update support, and native host integration, while the web application stays shared.
macOS supports self-update. Windows detects a new release and directs the user to the matching download rather than claiming an in-place update path it does not have.
RUNTIME TARGETS
One application, different platform pieces
TESTING & RELEASE PIPELINE
The current Python suite contains 24 modules and 171 passing tests. It covers application behavior, package validation, SSE shutdown, alternate configuration roots, and release smoke tests. I also check the provisioning scripts for shell syntax and expected behavior.
GitHub Actions builds Pi ARM64, macOS ARM64, macOS x64, and Windows x64. Each release asset is smoke-tested before upload, so the packaged app has to start successfully, not just the source tree.
RELEASE MATRIX
Four artifacts must pass their own smoke test
PI ARM64
Appliance package
MACOS ARM64
Packaged runtime
MACOS X64
Packaged runtime
WINDOWS X64
Packaged runtime
PROJECT SCALE
These are repository-level counts from the current audited build, not estimates of audience or traffic.
44
FASTAPI ROUTES
22
SQLITE TABLES
7
RETROACHIEVEMENTS ENDPOINTS
171
PYTHON TESTS
4
RELEASE PLATFORM JOBS
TEAM / ROLE
Nick Gray
Design
Development
Backend
Frontend
Deployment
Hardware Integration
CONCLUSION
LeftoverAchievements sits in an interesting middle ground for me. It’s a web application, but the main version lives on a Raspberry Pi connected to a touchscreen and is expected to start, update, recover, and run without feeling like a normal desktop computer.
That pushed the project into areas I hadn’t originally worked in as deeply: Linux sessions, systemd, packaging, release validation, service lifecycles, kiosk environments, and coordinating software with real hardware.
The part I like most is that all of that engineering is in service of something very simple: my brother and I want to know who’s winning.