docs: Enhance CLAUDE.md with comprehensive architecture documentation (#4)

Co-authored-by: Jonathan Gao <[email protected]>

Author: gsmlg

.claude/settings.local.json

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [ '*' ]
+
+jobs:
+  test:
+    name: Build and test
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Elixir
+        uses: erlef/setup-beam@v1
+        with:
+          elixir-version: '1.18'
+          otp-version: '28'
+
+      - name: Restore dependencies cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            deps
+            _build
+          key: ${{ runner.os }}-mix-${{ hashFiles('**/mix.lock') }}
+          restore-keys: ${{ runner.os }}-mix-
+
+      - name: Install dependencies
+        run: mix deps.get
+
+      - name: Compile
+        run: mix compile --warnings-as-errors
+
+      - name: Run Credo
+        run: mix credo --strict
+
+      - name: Build Dialyzer PLT (cached)
+        id: plt
+        uses: actions/cache@v4
+        with:
+          path: priv/plts
+          key: dialyzer-${{ hashFiles('mix.lock') }}
+
+      - name: Run Dialyzer
+        run: mix dialyzer --halt-exit-status
+

.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: Test
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Set up Elixir
+        uses: erlef/setup-beam@v1
+        with:
+          elixir-version: '1.18'
+          otp-version: '28'
+
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            deps
+            _build
+          key: ${{ runner.os }}-mix-${{ hashFiles('**/mix.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-mix-
+
+      - name: Install dependencies
+        run: |
+          mix local.hex --force
+          mix local.rebar --force
+          mix deps.get
+
+      - name: Run tests
+        run: mix test

.github/workflows/elixir.yml

@@ -14,10 +14,11 @@ This is Phoenix.SessionProcess, an Elixir library that creates a process for eac
 - `mix test test/path/to/specific_test.exs` - Run a specific test file
 - `mix compile` - Compile the project
 - `mix docs` - Generate documentation
+- `mix format` - Format code
 - `mix hex.publish` - Publish to Hex.pm (requires authentication)
 
 ### Testing
-The test suite uses ExUnit. Tests are located in the `test/` directory. The test helper starts the supervisor automatically.
+The test suite uses ExUnit. Tests are located in the `test/` directory. The test helper (test/test_helper.exs:3) automatically starts the supervisor.
 
 ### Development Environment
 The project uses `devenv` for development environment setup with Nix. Key configuration:
@@ -42,44 +43,63 @@ Expected performance:
 1. **Phoenix.SessionProcess** (lib/phoenix/session_process.ex:1)
    - Main module providing the public API
    - Delegates to ProcessSupervisor for actual process management
-   - Provides macros for creating session processes
+   - Provides two macros: `:process` (basic) and `:process_link` (with LiveView monitoring)
 
-2. **Phoenix.SessionProcess.Supervisor** (lib/phoenix/session_process/superviser.ex)
-   - Top-level supervisor that manages the Registry and ProcessSupervisor
+2. **Phoenix.SessionProcess.Supervisor** (lib/phoenix/session_process/superviser.ex:1)
+   - Top-level supervisor that manages the Registry, ProcessSupervisor, and Cleanup
    - Must be added to the application's supervision tree
 
-3. **Phoenix.SessionProcess.ProcessSupervisor** (lib/phoenix/session_process/process_superviser.ex)
+3. **Phoenix.SessionProcess.ProcessSupervisor** (lib/phoenix/session_process/process_superviser.ex:1)
    - DynamicSupervisor that manages individual session processes
    - Handles starting, terminating, and communicating with session processes
+   - Performs session validation and limit checks
 
 4. **Phoenix.SessionProcess.SessionId** (lib/phoenix/session_process/session_id.ex)
    - Plug that generates unique session IDs
    - Must be placed after `:fetch_session` plug
 
+5. **Phoenix.SessionProcess.Cleanup** (lib/phoenix/session_process/cleanup.ex:1)
+   - Automatic TTL-based session cleanup
+   - Schedules session expiration on creation
+
+6. **Phoenix.SessionProcess.Redux** (lib/phoenix/session_process/redux.ex:1)
+   - Redux-style state management with actions and reducers
+   - Provides time-travel debugging, middleware support, and action history
+
+7. **Phoenix.SessionProcess.State** (lib/phoenix/session_process/state.ex:1)
+   - Agent-based state storage with Redux-style dispatch support
+   - Used for simpler state management scenarios
+
 ### Process Management Flow
 
 1. Session ID generation via the SessionId plug
 2. Process creation through `Phoenix.SessionProcess.start/1-3`
-3. Processes are registered in `Phoenix.SessionProcess.Registry`
-4. Communication via `call/2-3` and `cast/2`
-5. Automatic cleanup when processes terminate
+3. Validation checks (session ID format, session limits)
+4. Processes are registered in `Phoenix.SessionProcess.Registry` with two entries:
+   - `{session_id, pid}` for session lookup
+   - `{pid, module}` for module tracking
+5. TTL-based cleanup is scheduled for each session
+6. Communication via `call/2-3` and `cast/2`
+7. Automatic cleanup when processes terminate or TTL expires
 
 ### Key Design Patterns
 
-- Uses Registry for process lookup by session ID
+- Uses Registry for bidirectional lookups (session_id ↔ pid, pid ↔ module)
 - DynamicSupervisor for on-demand process creation
-- Provides two macros: `:process` (basic) and `:process_link` (with LiveView monitoring)
-- Session processes can monitor LiveView processes and notify them on termination
+- Macros inject GenServer boilerplate and provide `get_session_id/0` helper
+- `:process_link` macro adds LiveView monitoring: sessions monitor LiveView processes and send `:session_expired` message on termination
+- Telemetry events for all lifecycle operations (start, stop, call, cast, cleanup, errors)
+- Comprehensive error handling with Phoenix.SessionProcess.Error module
 
 ## Configuration
 
 The library uses application configuration:
 ```elixir
 config :phoenix_session_process,
   session_process: MySessionProcess,  # Default session module
-  max_sessions: 10_000,                   # Maximum concurrent sessions
-  session_ttl: 3_600_000,                # Session TTL in milliseconds (1 hour)
-  rate_limit: 100                        # Sessions per minute limit
+  max_sessions: 10_000,               # Maximum concurrent sessions
+  session_ttl: 3_600_000,            # Session TTL in milliseconds (1 hour)
+  rate_limit: 100                    # Sessions per minute limit
 ```
 
 Configuration options:
@@ -91,20 +111,33 @@ Configuration options:
 ## Usage in Phoenix Applications
 
 1. Add supervisor to application supervision tree
-2. Add SessionId plug after fetch_session
-3. Define custom session process modules using the provided macros
+2. Add SessionId plug after fetch_session in router
+3. Define custom session process modules using `:process` or `:process_link` macros
 4. Start processes with session IDs
 5. Communicate using call/cast operations
 
+## State Management Options
+
+The library provides three state management approaches:
+
+1. **Basic GenServer** - Full control with standard GenServer callbacks
+2. **Phoenix.SessionProcess.State** - Agent-based with simple get/put and Redux dispatch
+3. **Phoenix.SessionProcess.Redux** - Full Redux pattern with actions, reducers, middleware, time-travel debugging
+
 ## Telemetry and Error Handling
 
 ### Telemetry Events
 The library emits comprehensive telemetry events for monitoring:
 - `[:phoenix, :session_process, :start]` - Session starts
 - `[:phoenix, :session_process, :stop]` - Session stops
+- `[:phoenix, :session_process, :start_error]` - Session start errors
 - `[:phoenix, :session_process, :call]` - Call operations
 - `[:phoenix, :session_process, :cast]` - Cast operations
+- `[:phoenix, :session_process, :communication_error]` - Communication errors
 - `[:phoenix, :session_process, :cleanup]` - Session cleanup
+- `[:phoenix, :session_process, :cleanup_error]` - Cleanup errors
+
+Events include metadata (session_id, module, pid) and measurements (duration in native time units).
 
 ### Error Types
 Common error responses:
@@ -113,4 +146,4 @@ Common error responses:
 - `{:error, {:session_not_found, session_id}}` - Session doesn't exist
 - `{:error, {:timeout, timeout}}` - Operation timed out
 
-Use `Phoenix.SessionProcess.Error.message/1` for human-readable error messages.
+Use `Phoenix.SessionProcess.Error.message/1` for human-readable error messages.

.github/workflows/test.yml

@@ -1,4 +1,3 @@
-{ pkgs, lib, config, inputs, ... }:
 
 let
   pkgs-stable = import inputs.nixpkgs-stable { system = pkgs.stdenv.system; };