Context

biking2 is a personal, single-writer web application that tracks bikes and mileage, converts Garmin TCX files to GPX, visualizes tracks and stats, and supports optional near real-time location tracking. It integrates with external systems and tools and is deployed on a constrained Linux host. Its arc42 architecture description documents goals, constraints, context, building blocks, runtime and deployment views, and explicit design decisions, providing a lightweight but structured architectural backbone for ongoing change.

biking2 was featured in the book Arc42 by example, which provides additional context. The project in github is now archived and the latest version resides at codeberg. The project was created by Michael Simons, who showcases the project and its use on his website.

This project illustrates how development on top of a platform architecture can make a hardware-dependent system feel like pure software development. The system would not function without physical components such as a fitness tracker and GPS hardware. Yet these hardware dependencies are encapsulated behind standardized interfaces and mature device ecosystems. As a result, the application developer interacts with stable APIs rather than raw hardware concerns.

Architect for Flow

The architecture decomposes the backend into cohesive functional modules (bikes, tracks, trips, locations, pictures, statistics) with clear responsibilities and narrow interfaces (primarily REST, plus oEmbed, WebSocket/STOMP, and MQTT). This explicit modular cut is an act of architectural boundary definition StrStructure. By making dependencies visible and restricting cross-module coupling, the system enables parallel development and isolated change DsnDesign.

The arc42 description reinforces this by documenting context, constraints, building blocks, runtime scenarios, and deployment topology. Architectural decisions such as isolating GPSBabel behind a dedicated module boundary and separating file storage from relational persistence are explicit commitments rather than incidental implementation details CmtCommit.

When performance and analytical complexity increased, the statistics module evolved from in-memory Java 8 stream processing to a database-centric approach using jOOQ and analytic SQL functions. This change did not ripple uncontrollably through the system because the statistics module had a clearly defined responsibility and API. The architecture absorbed change locally EvoEvolve, demonstrating flow preservation across iterations. In Velocity Loop terms, System Stewardship establishes and maintains structural integrity StrStructure, enabling Engineering to implement and refine modules predictably DsnDesign without destabilizing Delivery.

Shift Left

Key constraints and risks are addressed early and structurally. External integrations (RSS feeds, GPSBabel CLI, MQTT broker) are isolated behind dedicated components, making them mockable and testable without live dependencies VrfVerify. This reduces late integration surprises and allows validation of assumptions during development rather than in production CstConstruct.

Quality goals such as testability and understandability are translated into concrete architectural rules: constructor injection to avoid hidden dependencies, repository isolation, module-level boundaries, and high automated test coverage. These decisions reflect early architectural intent rather than retrofitted quality controls DsnDesign.

The later shift to jOOQ illustrates continued leftward risk handling. Instead of allowing performance bottlenecks and analytical complexity to accumulate in application code, the design moved computation closer to the data model, leveraging database capabilities explicitly. This reduced hidden complexity in the application layer and clarified responsibility boundaries EvoEvolve.

In Velocity Loop terms, early structural clarity StrStructure strengthens downstream Delivery activities such as packaging and deployment PkgPackage, while strong verification practices VrfVerify reduce operational surprises. Architectural intent is embedded before scaling pressure forces reactive change.

Outcome

A lightweight, document-based arc42 description was sufficient to keep the system understandable and evolvable while it accumulated integrations (conversion tooling, feeds, messaging) and underwent significant internal evolution (notably in the statistics approach). The result is a practical example of how structured documentation, clear modular boundaries, and explicit decisions can sustain change and learning without requiring heavyweight modeling.