STYX Workout Tracker | Mohamad Meri

Project Goal

Build a personal project with the discipline and quality standards of a high-performing engineering team. The focus was on creating robust, maintainable, and well-tested backend systems rather than rushing to implement UI features.

Core Principle: Build systems that are production-ready from day one, with emphasis on reliability over rapid feature delivery.

Current Features

RESTful API for workout session management
Relational database with SQLite backend
Custom CLI for database operations
Comprehensive test suite with property-based testing
Automated CI/CD pipeline
Modular, decoupled architecture

Architecture & Design Decisions

Separation of Concerns

The application follows a modular architecture that separates business logic, data access, and configuration management into distinct, testable layers.

          styx/
          ├── api/              # Flask routes and request handling
          ├── models/           # Database models and business logic
          ├── config/           # Custom configuration management package
          ├── cli/              # Command-line interface for dev operations
          └── tests/            # Comprehensive test suite
          

Each layer has a single responsibility, making the codebase easier to test, debug, and extend. Changes to one layer rarely require modifications to others.

Engineering Challenges & Solutions

Real problems encountered and how I solved them

Challenge: Fragile Configuration System

Problem: Initial implementation used hardcoded file paths for configuration. Tests failed when run from different directories, causing the entire application to crash with file-not-found errors.

Root Cause: Fragile dependency on current working directory made the application environment-sensitive.

Solution: Engineered a decoupled configuration sub-package that intelligently searches up the directory tree to locate config.toml regardless of execution context. Includes robust error handling and its own unit tests.

Impact: Transformed a brittle, environment-dependent system into a robust, portable application that runs reliably in any context.

Challenge: Ensuring Code Reliability

Problem: Manual testing is insufficient for catching edge cases and ensuring long-term reliability as the codebase grows.

Solution: Implemented a multi-layered automated testing strategy combining traditional unit tests with property-based testing using Hypothesis.

How it Works: Instead of writing dozens of example-based tests, I define properties that should always hold true. Hypothesis then generates hundreds of test cases automatically, including edge cases I never would have considered.

Result: High confidence in code correctness with automated detection of subtle bugs that would be missed by manual testing.

Advanced Testing Strategy

Testing is the cornerstone of this project's reliability. The test suite combines multiple approaches:

Unit Tests (Pytest): Validate individual components in isolation with clear, readable test cases
Property-Based Testing (Hypothesis): Define invariants and let Hypothesis generate edge cases automatically. Example: "The API should never crash with valid input, regardless of what that input is"
Integration Tests: Verify that components work correctly together, especially database interactions
Test Fixtures: Consistent, reproducible test environments for reliable results

Every test runs automatically on every commit via GitHub Actions CI pipeline, preventing regressions before they reach the main branch.

DevOps & Continuous Integration

GitHub Actions

Automated CI pipeline runs on every commit:

Install dependencies
Run full test suite
Execute linter (Ruff)
Generate coverage report
Block merge if tests fail

Code Quality (Ruff)

High-performance linter enforces consistent code style across the entire project.

Catches common mistakes, enforces PEP 8 standards, and ensures readability without manual code reviews.

Coverage Tracking

Coveralls integration monitors test coverage to ensure new code is accompanied by tests.

Prevents untested code from entering the codebase.

Developer Experience: Custom CLI

Built command-line tools to streamline the development workflow and reduce friction:

            # Initialize database with schema
            $ flask db init

            # Seed database with test data for development
            $ flask db seed

            # Complete teardown and rebuild
            $ flask db reset
            

Impact: Reduced database setup time from manual SQL execution to a single command, dramatically speeding up the development and testing loop.

Current Status

Backend development phase is nearing completion with:

Core architecture finalized
Database schema and models complete
Testing infrastructure operational
CI/CD pipeline active and enforcing quality
API endpoints for workout CRUD operations

Next Steps

Finalize remaining API endpoints
Implement authentication and authorization
Begin frontend development with modern JavaScript framework
Deploy to cloud platform for live demo
Add API documentation (Swagger/OpenAPI)

Technology Stack

Backend

Python, Flask, SQLAlchemy

Database

SQLite

Testing

Pytest, Hypothesis, Coveralls

DevOps

GitHub Actions, Ruff, Docker