Liftlyf Technical Documentation

Engineering the Liftlyf platform.

Liftlyf is a full-stack workout tracking application. The project combines native Android development, local data persistence, offline-first synchronization, HTTP-based APIs, backend services, authentication, relational databases, containerization and cloud deployment.

01. Project Overview

Liftlyf is designed around a simple product goal: provide users with a focused way to record workouts and maintain a history of their training.

From an engineering perspective, the project extends beyond the Android application itself. It includes a native mobile client, local data persistence, synchronization APIs, backend services, authentication, persistent relational storage and hosted cloud infrastructure.

Layer Technology Responsibility
Mobile Client Kotlin / Jetpack Compose User interface and application logic
Local Storage Room On-device structured persistence
Networking Retrofit / HTTP Communication with backend APIs
Backend Spring Boot Business logic and server-side services
Security Spring Security / JWT Authentication and protected endpoints
Database PostgreSQL Persistent server-side relational data
Containerization Docker Portable backend runtime environment
Domain / DNS Cloudflare Domain and DNS management for Liftlyf services
Cloud Hosting Oracle Cloud Infrastructure Hosted backend infrastructure
Automation GitHub Actions Build and deployment automation

02. System Architecture

Liftlyf follows a client-server architecture. The Android application acts as the client and maintains local application data, while the backend provides server-side services, authentication and persistent remote storage.

Android Application
Kotlin + Jetpack Compose
↓
Local Data Layer
Room Database
↓
Synchronization Layer
Repository + Retrofit + HTTP
↓
Spring Boot Backend
Controllers → Services → Persistence
↓
PostgreSQL Database
The architecture separates presentation, local persistence, synchronization, API communication, backend business logic and server-side storage into distinct layers.

03. Android Application

The Liftlyf Android client is built using Kotlin and Jetpack Compose. Jetpack Compose provides a declarative approach to constructing the application's user interface.

Presentation Layer

The presentation layer is responsible for displaying application state and receiving user interactions. Screens represent the user interface for features such as workout tracking, exercise management and workout history.

State & Data Flow

User Interaction ↓ UI Event ↓ Application Logic ↓ Repository / Data Layer ↓ Room Database ↓ Updated Local State ↓ UI Recomposition

The local database acts as part of the application's primary data layer, allowing the user interface to work with persisted local state rather than depending on every action completing through a remote network request.

Jetpack Compose

Declarative UI framework responsible for rendering application screens from application state.

Room

Structured on-device persistence built on top of SQLite.

Retrofit

Typed HTTP communication between the Android client and Liftlyf backend APIs.

Kotlin

Primary language for Android application development and application logic.

04. Offline-First Data & Synchronization

Liftlyf uses a local-first approach to workout data. When a user records or updates workout information, the application can first work with locally persisted data instead of requiring every user action to wait for a remote backend response.

Local-First Workflow

User records workout data ↓ Android application processes the update ↓ Data is written to Room ↓ UI reads the updated local state ↓ Workout remains available on the device ↓ Synchronization layer prepares remote request ↓ Data is sent to the Liftlyf backend ↓ Spring Boot processes the request ↓ PostgreSQL is updated

This separates the immediate user experience from remote persistence. The user interacts with locally available data while the synchronization layer is responsible for communication with the backend.

Synchronization Responsibilities

  • Maintain locally persisted workout data through Room.
  • Prepare application data for remote synchronization.
  • Convert local application data into API request objects.
  • Send requests to the backend through Retrofit.
  • Receive backend responses after synchronization processing.
  • Maintain a clear boundary between local and remote data layers.
The synchronization architecture allows local storage and remote persistence to serve different responsibilities: Room supports immediate on-device data access, while PostgreSQL provides server-side persistence through the backend.

05. Synchronization API

Synchronization between the Android application and the Liftlyf backend is performed through the API layer. Retrofit is used by the Android client to communicate with backend endpoints over HTTP.

Room Database ↓ Repository / Synchronization Logic ↓ Retrofit ↓ HTTP Request ↓ Liftlyf Backend API ↓ Spring Security ↓ Controller ↓ Service Layer ↓ Persistence Layer ↓ PostgreSQL ↓ HTTP Response ↓ Android Application

How the Sync Boundary Works

The Android application does not directly connect to PostgreSQL. Room and PostgreSQL exist in different environments and serve different purposes. The synchronization API acts as the controlled boundary between the mobile application's local data and the backend's persistent database.

Local application data is transformed into structured request data and sent through the backend API. The backend receives the request, applies authentication and application-level processing, then persists the relevant data through its server-side data layer.

Conceptual Synchronization Request

Android Application ↓ Synchronization Logic ↓ Retrofit Request ↓ HTTP API Request ↓ Spring Security ↓ Sync Controller ↓ Service Layer ↓ Persistence Layer ↓ PostgreSQL ↓ Response Returned to Client

Why Use a Synchronization API?

  • The Android application remains independent from PostgreSQL.
  • Database credentials are never exposed directly to the client.
  • The backend controls validation and persistence logic.
  • Authentication can be enforced before protected data is processed.
  • The backend API provides a consistent contract between mobile and server.
  • The server-side implementation can evolve independently of the Android UI.

06. Backend Architecture

The Liftlyf backend is built using Spring Boot. Its role is to expose application services through APIs and provide a server-side boundary for business logic, authentication and persistent data access.

HTTP Request ↓ Spring Security Filter Chain ↓ Controller ↓ Service Layer ↓ Repository / Persistence Layer ↓ PostgreSQL ↓ Response DTO / HTTP Response

Controller Layer

Controllers define the HTTP API boundary. They receive requests, map incoming data and delegate application operations to the appropriate backend service layer.

Service Layer

The service layer contains server-side application logic and coordinates operations between the API boundary and the persistence layer.

Persistence Layer

Database access is separated from higher-level application logic. This keeps persistence concerns isolated from API handling and backend business operations.

07. Authentication & Security

The backend uses Spring Security to protect application resources. JWT-based authentication provides a mechanism for authenticated clients to prove their identity when accessing protected backend endpoints.

Authentication Flow

User authenticates ↓ Backend validates credentials ↓ Authentication token is issued ↓ Client includes token with protected requests ↓ Spring Security validates request authentication ↓ Authorized request continues to backend services

Security Responsibilities

  • User authentication.
  • Protection of authenticated API endpoints.
  • Validation of authentication tokens.
  • Authorization of protected requests.
  • Separation of public and authenticated resources.
  • Keeping direct database access away from the mobile client.

08. Database Architecture

Liftlyf uses two distinct persistence layers for different environments. Room provides structured local persistence on the Android device, while PostgreSQL provides persistent relational storage for backend-managed data.

Android Application
↓
Room
Local Device Database
↕
Synchronization API
↕
PostgreSQL
Remote Backend Database

Conceptual Data Relationships

User ↓ Workout ↓ Exercises Performed ↓ Individual Sets ↓ Training Data

A relational database structure is well suited for storing structured workout information and the relationships between users, workouts, exercises and training records.

Local vs Server Storage

Room

Supports structured, locally available workout data on the Android device.

PostgreSQL

Provides persistent server-side relational storage accessed through the Liftlyf backend.

09. Deployment & Infrastructure

The Liftlyf backend is containerized using Docker and hosted on Oracle Cloud Infrastructure.

Domain & Network Layer

The Liftlyf domain, liftlyf.com, is managed through Cloudflare and provides the public domain layer for Liftlyf services. DNS configuration connects Liftlyf services to infrastructure running on Oracle Cloud.

The backend itself is hosted on an Oracle Cloud VM, where the Spring Boot application runs inside a Docker container. Cloudflare and Oracle Cloud therefore serve different responsibilities: Cloudflare manages the public domain and DNS layer, while Oracle Cloud provides the compute infrastructure used to run the backend.

Runtime Infrastructure

Android Application
↓
liftlyf.com
↓
Cloudflare
Domain & DNS
↓
Oracle Cloud Infrastructure
↓
Oracle Cloud VM
↓
Docker Container
↓
Spring Boot Backend
↓
PostgreSQL Database

Why Containerization?

  • Provides a consistent runtime environment.
  • Packages the backend with its runtime dependencies.
  • Reduces differences between development and deployment.
  • Simplifies repeatable backend deployment.
  • Allows backend versions to be deployed as container images.

Cloud Hosting

Hosting the backend on an Oracle Cloud VM allows Liftlyf services to run independently from a local development machine and be accessed remotely by application clients.

10. CI/CD & Automation

GitHub Actions provides an automation layer around the project's development and deployment workflow.

Developer pushes code ↓ GitHub repository receives change ↓ GitHub Actions workflow starts ↓ Build / Test / Automation steps ↓ Deployment workflow ↓ Updated application or backend

Automation Goals

  • Reduce repetitive manual work.
  • Standardize build processes.
  • Make deployment more repeatable.
  • Create a foundation for automated testing.
  • Improve consistency between development and deployment.

11. Engineering Decisions

Native Android Development

Kotlin and Jetpack Compose provide a modern native Android development stack while allowing Liftlyf to integrate directly with Android platform capabilities.

Local-First Data

Room provides locally persisted data that can support a responsive application experience without requiring every user interaction to wait for a backend request.

Client-Server Separation

A dedicated backend separates mobile application concerns from server-side business logic, authentication and database access.

API-Based Synchronization

The synchronization API provides a controlled interface between the Android application's local data and the PostgreSQL database. The mobile client communicates with the backend rather than directly accessing server-side infrastructure.

Containerized Backend

Docker provides a reproducible runtime environment for backend deployment on the Oracle Cloud VM.

Cloud Infrastructure

Oracle Cloud provides the compute infrastructure required to run the backend remotely, while Cloudflare provides the public domain and DNS layer for Liftlyf services.

12. Future Engineering Roadmap

Liftlyf will continue evolving beyond its initial release. Future work includes both user-facing functionality and continued improvements to the underlying engineering platform.

Progress Analytics

Visualizations and data analysis for long-term training history and performance trends.

Cardio & Timers

Additional workout modes, cardio tracking and configurable workout or rest timers.

Push Notifications

Workout reminders and notification infrastructure.

AI Features

Future intelligent features to provide training insights and assistance.

Observability

Improved backend logging, error reporting, crash analysis and application monitoring.

Infrastructure

Continued improvements to deployment automation, reliability, security and production infrastructure.

Liftlyf is intended to remain an evolving full-stack engineering project. This documentation will continue to expand as the application architecture, infrastructure and feature set evolve.