Refactor: Worker-based appraisal with Redis caching

.github/workflows/api.yml

@@ -16,24 +16,26 @@ on:
 
 # A workflow is defined of one or more jobs that can run sequentially or in parallel
 jobs:
-  # This workflow contains a single job called "api_test"
   api_test:
-    strategy:
-      # don't cancel other jobs if one fails
-      fail-fast: false
-      # maximum number of jobs that can run simultaneously
-      max-parallel: 1
-      matrix:
-        os: [ubuntu, macos]
-    runs-on: ${{ matrix.os }}-latest  # Runs on latest builds of matrix OSes
+    runs-on: ubuntu-latest
     env:
       BUNDLE_WITHOUT: production # skip installing production gem (pg)
-    # Steps represent a sequence of tasks that will be executed as part of the job
+
+    # Redis service container for caching
+    services:
+      redis:
+        image: redis
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
     steps:
-      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-      - uses: actions/checkout@v4
-
-      # Builds on a predefined action that has Ruby installed 
+      - uses: actions/checkout@v6
+
       - uses: ruby/setup-ruby@v1
         with:
           bundler-cache: true # runs 'bundle install' and caches installed gems automatically
@@ -49,7 +51,8 @@ jobs:
           DB_FILENAME: ${{ secrets.DB_FILENAME }}
           REPOSTORE_PATH: ${{ secrets.REPOSTORE_PATH }}
           API_HOST: ${{ secrets.API_HOST }}
-          CLONE_QUEUE_URL: ${{ secrets.CLONE_QUEUE_URL }}
+          REDIS_URL: ${{ secrets.REDIS_URL }}
+          WORKER_QUEUE_URL: ${{ secrets.WORKER_QUEUE_URL }}
           AWS_REGION: ${{ secrets.AWS_REGION }}
           AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
           AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

.gitignore

@@ -1,10 +1,11 @@
 .claude/
 CLAUDE.md
+CLAUDE.local.md
 _snippets/
 .bundle/
 config/secrets.yml
 coverage/*
 !coverage/.resultset.json
 *.db
 repostore/**/
-_cache/
+spec/logs/

Gemfile

@@ -28,9 +28,7 @@ gem 'dry-transaction', '~> 0'
 gem 'dry-validation', '~> 1.0'
 
 # Caching
-gem 'rack-cache', '~> 1.13'
 gem 'redis', '~> 4.8'
-gem 'redis-rack-cache', '~> 2.2'
 
 # DOMAIN LAYER
 # Validation

Gemfile.lock

@@ -5,8 +5,8 @@ GEM
       public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     aws-eventstream (1.4.0)
-    aws-partitions (1.1190.0)
-    aws-sdk-core (3.239.2)
+    aws-partitions (1.1198.0)
+    aws-sdk-core (3.240.0)
       aws-eventstream (~> 1, >= 1.3.0)
       aws-partitions (~> 1, >= 1.992.0)
       aws-sigv4 (~> 1.9)
@@ -22,7 +22,7 @@ GEM
     base64 (0.3.0)
     bigdecimal (3.3.1)
     coderay (1.1.3)
-    concurrent-ruby (1.3.5)
+    concurrent-ruby (1.3.6)
     cookiejar (0.3.4)
     crack (1.0.1)
       bigdecimal
@@ -113,9 +113,9 @@ GEM
       rake
     figaro (1.3.0)
       thor (>= 0.14.0, < 2)
-    flog (4.8.0)
-      path_expander (~> 1.0)
-      ruby_parser (~> 3.1, > 3.1.0)
+    flog (4.9.1)
+      path_expander (~> 2.0)
+      prism (~> 1.7)
       sexp_processor (~> 4.8)
     hashdiff (1.2.1)
     hirb (0.7.3)
@@ -130,7 +130,7 @@ GEM
     http_parser.rb (0.8.0)
     ice_nine (0.11.2)
     jmespath (1.6.2)
-    json (2.17.1)
+    json (2.18.0)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     listen (3.9.0)
@@ -142,7 +142,7 @@ GEM
     logger (1.7.0)
     method_source (1.1.0)
     mini_portile2 (2.8.9)
-    minitest (5.26.2)
+    minitest (5.27.0)
     minitest-rg (5.3.0)
       minitest (~> 5.0)
     multi_json (1.18.0)
@@ -153,11 +153,11 @@ GEM
     parser (3.3.10.0)
       ast (~> 2.4.1)
       racc
-    path_expander (1.1.3)
+    path_expander (2.0.0)
     pg (1.6.2)
     pg (1.6.2-arm64-darwin)
     pg (1.6.2-x86_64-linux)
-    prism (1.6.0)
+    prism (1.7.0)
     pry (0.15.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
@@ -166,8 +166,6 @@ GEM
       nio4r (~> 2.0)
     racc (1.8.1)
     rack (3.2.4)
-    rack-cache (1.17.0)
-      rack (>= 0.4)
     rack-session (0.3.0)
       rack (>= 3.0.0.beta1)
     rack-test (2.2.0)
@@ -178,11 +176,6 @@ GEM
     rb-inotify (0.11.1)
       ffi (~> 1.0)
     redis (4.8.1)
-    redis-rack-cache (2.2.1)
-      rack-cache (>= 1.10, < 2)
-      redis-store (>= 1.6, < 2)
-    redis-store (1.11.0)
-      redis (>= 4, < 6)
     reek (6.5.0)
       dry-schema (~> 1.13)
       logger (~> 1.6)
@@ -199,17 +192,17 @@ GEM
     rexml (3.4.4)
     roar (1.2.0)
       representable (~> 3.1)
-    roda (3.98.0)
+    roda (3.99.0)
       rack
-    rubocop (1.81.7)
+    rubocop (1.82.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
       parallel (~> 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.47.1, < 2.0)
+      rubocop-ast (>= 1.48.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
     rubocop-ast (1.48.0)
@@ -226,9 +219,6 @@ GEM
       lint_roller (~> 1.1)
       rubocop (>= 1.72.1, < 2)
     ruby-progressbar (1.13.0)
-    ruby_parser (3.21.1)
-      racc (~> 1.5)
-      sexp_processor (~> 4.16)
     sequel (5.99.0)
       bigdecimal
     sexp_processor (4.17.4)
@@ -249,7 +239,7 @@ GEM
     uber (0.1.0)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
-    unicode-emoji (4.1.0)
+    unicode-emoji (4.2.0)
     vcr (6.3.1)
       base64
     webmock (3.26.1)
@@ -260,7 +250,7 @@ GEM
       base64
       websocket-extensions (>= 0.1.0)
     websocket-extensions (0.1.5)
-    zeitwerk (2.7.3)
+    zeitwerk (2.7.4)
 
 PLATFORMS
   arm64-darwin-24
@@ -290,12 +280,10 @@ DEPENDENCIES
   pg (~> 1.0)
   pry
   puma (~> 6.0)
-  rack-cache (~> 1.13)
   rack-session (~> 0)
   rack-test
   rake (~> 13.0)
   redis (~> 4.8)
-  redis-rack-cache (~> 2.2)
   reek
   rerun
   roar (~> 1.1)

Procfile

@@ -1,3 +1,3 @@
 release: rake db:migrate; rake queues:create
 web: bundle exec puma -t 5:5 -p ${PORT:-3000} -e ${RACK_ENV:-development}
-worker: bundle exec shoryuken -r ./workers/git_clone_worker.rb -C ./workers/shoryuken.yml
+worker: bundle exec shoryuken -r ./workers/application/controllers/worker.rb -C ./workers/shoryuken.yml

README.md

@@ -1,6 +1,87 @@
 # CodePraise Web API
 
-Web API that allowsGithub *projects* to be *appraised* for inidividual *contributions* by *members* of a team.
+Web API that allows Github *projects* to be *appraised* for individual *contributions* by *members* of a team.
+
+## Setup
+
+### Prerequisites
+
+1. **Ruby** - See `.ruby-version` for required version
+2. **Redis** - Required for caching appraisal results
+3. **AWS Account** - For SQS message queue (worker communication)
+
+### Install Redis
+
+**Using rake tasks (recommended):**
+
+```bash
+rake redis:start    # Start Redis Docker container
+rake redis:stop     # Stop Redis when done
+rake redis:status   # Check connectivity
+```
+
+**Or manually with Homebrew (macOS):**
+
+```bash
+brew install redis
+brew services start redis
+```
+
+### Install Dependencies
+
+```bash
+bundle install
+```
+
+### Configure Secrets
+
+```bash
+cp config/secrets_example.yml config/secrets.yml
+```
+
+Edit `config/secrets.yml` and add your:
+
+- `GITHUB_TOKEN` - GitHub personal access token
+- AWS credentials for SQS queue
+
+### Setup Database
+
+```bash
+bundle exec rake db:migrate                  # Development database
+RACK_ENV=test bundle exec rake db:migrate    # Test database
+```
+
+### Verify Setup
+
+```bash
+rake redis:status    # Check Redis connectivity
+rake queues:status   # Check SQS queue status
+```
+
+## Running the Application
+
+```bash
+rake run             # Start API server on port 9090
+rake worker:run:dev  # Start background worker (in separate terminal)
+```
+
+## Testing
+
+```bash
+rake spec            # Run unit and integration tests
+bash spec/acceptance_tests   # Run full acceptance tests (starts worker automatically)
+```
+
+## Architecture
+
+This project uses **Clean Architecture** with separate DDD-style layers for the API and background worker:
+
+- **API (`app/`)**: Handles HTTP requests, database, GitHub integration
+- **Worker (`workers/`)**: Handles git clone/blame operations, Redis caching
+
+Both use parallel layer structures: `domain/`, `infrastructure/`, `presentation/`, `application/`
+
+See `CLAUDE.md` for detailed architecture documentation.
 
 ## Routes