airstation - Moses Yebei

The Problem

The codebase exhibits high cognitive load and widespread duplication that increases the risk of regressions during modifications. Static analysis found maximum indentation depth of 8 in critical playback and library files, alongside 62 repeated 6-line logic blocks across a dozen files. For a self-hosted streaming application where the pipeline involves FFmpeg, SQLite, and HLS generation, these maintainability issues represent a tangible operational risk.

What This Does

Airstation is a self-hosted web application for streaming music over the Internet. The frontend is split between web/player (a minimalistic listener interface) and web/studio (an upload and management dashboard). Under the hood, the system stores track metadata and queue state in SQLite, processes audio via FFmpeg (defined in internal/pkg/ffmpeg/ffmpeg.go), and serves streams using HTTP-based HLS segmentation. The entire stack is packaged for Docker deployment, with the Go backend (internal/) handling all server logic, persistence, and external command orchestration.

How It Is Wired

Execution begins at cmd/main.go:18, which reaches 68 functions and serves as the process entry point. From there, Run in internal/http/server.go:59 acts as the central hub, reaching 54 functions and being called from 9 distinct places. This function registers request handlers (defined in internal/http/handlers.go, which contains 24 handlers including handleTracks, handleHLSPlaylist, and handleEvents) and manages the event loop via listenEvents.

The data path typically flows from an HTTP request through the handlers into the storage layer (internal/storage/sqlite/), which provides the New, Close, and Instance functions for database interaction. Audio processing is offloaded to internal/pkg/ffmpeg/ffmpeg.go, which runs external commands for tasks like MakeHLSPlaylist, TrimAudio, and PadAudio. A traced path from the entry point to an external effect is main -> New -> db via db.Exec, and Run -> DeleteOldPlaybackHistory [db via ps.db.Exec].

The module graph shows internal/http/handlers.go as a high-degree hub (24 functions, called from 1 other file, calls into 15), making it a focal point for any web-layer changes. Conversely, the web/studio/src/page/Playback.tsx, web/studio/src/page/Playlists.tsx, and web/studio/src/page/TracksLibrary.tsx files suffer from deep nesting (max depth 8), complicating control flow.

How To Use It

Setup:

docker-compose up --build

The docker-compose.yml orchestrates the services. Configuration is driven by environment variables read via getEnv calls throughout internal/station/service.go and internal/http/server.go. No .env file is committed to the repository; users must supply the required variables (details within the README or inferred from the Go code) at runtime.

Running it: The process starts with go run cmd/main.go or via the Docker entrypoint. The studio UI is typically accessible at the mapped port after containers initialize.

Real-World Use

A developer wishing to add a new track upload limit modifies internal/http/handlers.go where handleTracksUpload validates inbound requests. The upload flows through the handler into internal/storage/sqlite/queue.go or track.go for persistence. Subsequently, FFmpeg processes the file via internal/pkg/ffmpeg/ffmpeg.go to generate HLS segments, after which the listener player (web/player/src/page/CurrentTrack.tsx) picks up the playlist automatically.

Code Health & Issues

Measured findings from static analysis:

[HIGH/cognitive_load] Deep nesting x12 — files: web/studio/src/page/Playback.tsx, web/studio/src/page/Playlists.tsx, web/studio/src/page/TracksLibrary.tsx (max indentation depth 8).
[HIGH/clarity] Duplicated code blocks — 62 repeated 6-line blocks across 12 files, including internal/storage/sqlite/queue.go, internal/storage/sqlite/track.go, web/player/src/api/index.ts, and web/studio/src/api/index.ts.
[MEDIUM/cognitive_load] High branching density x2 — files: web/player/src/page/StationInformation.tsx, internal/station/service.go (32 branch points over 94 lines).

SDLC observations:

GitHub Actions pins third-party actions to mutable tags (@v3, @v5), risking secret exposure if action owners update versions.
No Dependabot or Renovate configuration; 3 dependency manifests are unmonitored for updates.
Dockerfile uses mutable base image tags (node:22-alpine, golang:1.26-alpine).
Test coverage is minimal (2 test files against 102 source files, a ratio of 0.020).
No USER directive in the Dockerfile; processes run as root by default.

The Bottom Line

Airstation functionalizes a compact, Dockerized radio streaming stack with React and Go, but the codebase carries significant technical debt. The duplication and nesting patterns found in the playback and API layers mean that straightforward feature additions carry a higher-than-ideal risk of introducing bugs. It is suitable for hobbyists or small teams needing a quick self-hosted solution, but engineering teams prioritizing long-term maintainability should budget time for refactoring the duplicated logic and flattening the control flow before productionizing the setup.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

171 files

Go45
TypeScript34
TSX23
JSON10
CSS9
Markdown6

ReactExpressDocker

Module dependencies

The 10 most depended-upon modules of 57, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_web_studio_src_api_types["types"] n1_web_studio_src_api_index["index"] n2_udio_src_notifications_index["index"] n3_web_studio_src_icons_index["index"] n4_web_player_src_store_events["events"] n5_web_player_src_api_index["index"] n6_studio_src_store_track_queue["track-queue"] n7_web_studio_src_utils_time["time"] n8_eb_studio_src_store_playback["playback"] n9_web_player_src_store_history["history"] n4_web_player_src_store_events --> n5_web_player_src_api_index n1_web_studio_src_api_index --> n0_web_studio_src_api_types n8_eb_studio_src_store_playback --> n0_web_studio_src_api_types n8_eb_studio_src_store_playback --> n1_web_studio_src_api_index n8_eb_studio_src_store_playback --> n2_udio_src_notifications_index n8_eb_studio_src_store_playback --> n7_web_studio_src_utils_time n6_studio_src_store_track_queue --> n0_web_studio_src_api_types n6_studio_src_store_track_queue --> n1_web_studio_src_api_index

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium6

low2

Pin third-party GitHub Actions to a commit SHAhigh3 occurrences

.github/workflows

docker/setup-buildx-action@v3, docker/login-action@v3, docker/build-push-action@v5

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/docker-image.yml

1 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

3 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium4 occurrences

Dockerfile

node:22-alpine, node:22-alpine, golang:1.26-alpine (mutable tag)

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Expand the test suite; it cannot cover this codebasemedium2 occurrences

2 test files against 102 source files (ratio 0.020)

A reviewer reads "has tests" and assumes a safety net that covers two files out of eighty-five, which is how untested paths ship behind a green badge.

Fix: Add tests for the highest fan-in modules first.

Set timeout-minutes on the workflow jobslow

.github/workflows/docker-image.yml

1 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.