feat: enhance documentation and add comprehensive module docs

- Add detailed documentation for all core modules including cleanup, config, error handling
- Expand README with installation guide, quick start, and advanced usage examples
- Add performance benchmarks and development environment setup instructions
- Include comprehensive telemetry events and error handling documentation
- Add semantic versioning compatibility and contribution guidelines

Author: GSMLG-BOT

CLAUDE.md

@@ -19,6 +19,22 @@ This is Phoenix.SessionProcess, an Elixir library that creates a process for eac
 ### Testing
 The test suite uses ExUnit. Tests are located in the `test/` directory. The test helper starts the supervisor automatically.
 
+### Development Environment
+The project uses `devenv` for development environment setup with Nix. Key configuration:
+- Uses Elixir/BEAM 27
+- Runs `hello` script on shell entry for greeting
+- Includes git, figlet, and lolcat tools
+
+### Benchmarking
+Performance testing available via:
+- `mix run bench/simple_bench.exs` - Quick benchmark (5-10 seconds)
+- `mix run bench/session_benchmark.exs` - Comprehensive benchmark (30-60 seconds)
+
+Expected performance:
+- Session Creation: 10,000+ sessions/sec
+- Memory Usage: ~10KB per session
+- Registry Lookups: 100,000+ lookups/sec
+
 ## Architecture
 
 ### Core Components
@@ -59,15 +75,42 @@ The test suite uses ExUnit. Tests are located in the `test/` directory. The test
 
 The library uses application configuration:
 ```elixir
-config :phoenix_session_process, session_process: MySessionProcess
+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
 ```
 
-This sets the default module to use when starting session processes without specifying a module.
+Configuration options:
+- `session_process`: Default module for session processes (defaults to `Phoenix.SessionProcess.DefaultSessionProcess`)
+- `max_sessions`: Maximum concurrent sessions (defaults to 10,000)
+- `session_ttl`: Session TTL in milliseconds (defaults to 1 hour)
+- `rate_limit`: Sessions per minute limit (defaults to 100)
 
 ## 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
 4. Start processes with session IDs
-5. Communicate using call/cast operations
+5. Communicate using call/cast operations
+
+## 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, :call]` - Call operations
+- `[:phoenix, :session_process, :cast]` - Cast operations
+- `[:phoenix, :session_process, :cleanup]` - Session cleanup
+
+### Error Types
+Common error responses:
+- `{:error, {:invalid_session_id, session_id}}` - Invalid session ID format
+- `{:error, {:session_limit_reached, max_sessions}}` - Maximum sessions exceeded
+- `{: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.

README.md

@@ -1,17 +1,32 @@
 # Phoenix.SessionProcess
 
-Create a process for each user session, all user requests go through this process. This provides session isolation, state management, and automatic cleanup with TTL support.
+[![Hex Version](https://img.shields.io/hexpm/v/phoenix_session_process.svg)](https://hex.pm/packages/phoenix_session_process)
+[![Hex Docs](https://img.shields.io/badge/docs-hexpm-blue.svg)](https://hexdocs.pm/phoenix_session_process/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
-* [Github Repo](https://github.com/gsmlg-dev/phoenix_session_process)
+A powerful Phoenix library that creates a dedicated process for each user session. All user requests go through their dedicated session process, providing complete session isolation, robust state management, and automatic cleanup with TTL support.
+
+## Why Phoenix.SessionProcess?
+
+Traditional session management stores session data in external stores (Redis, database) or relies on plug-based state. **Phoenix.SessionProcess** takes a different approach by giving each user their own GenServer process, enabling:
+
+- **Real-time session state** without external dependencies
+- **Perfect session isolation** - no shared state between users
+- **Built-in LiveView integration** for reactive UIs
+- **Automatic memory management** with configurable TTL
+- **Enterprise-grade performance** - 10,000+ sessions/second
+- **Zero external dependencies** beyond core Phoenix/OTP
 
 ## Features
 
 - **Session Isolation**: Each user session runs in its own GenServer process
-- **Automatic Cleanup**: TTL-based automatic session cleanup
-- **Configuration Management**: Configurable TTL, session limits, and rate limiting
+- **Automatic Cleanup**: TTL-based automatic session cleanup and memory management
 - **LiveView Integration**: Built-in support for monitoring LiveView processes
+- **High Performance**: Optimized for 10,000+ concurrent sessions
+- **Configuration Management**: Configurable TTL, session limits, and rate limiting
 - **Extensible**: Custom session process modules with full GenServer support
-- **Validation**: Session ID validation and concurrent session limits
+- **Comprehensive Monitoring**: Built-in telemetry and performance metrics
+- **Error Handling**: Detailed error reporting and human-readable messages
 
 ## Installation
 
@@ -25,6 +40,12 @@ def deps do
 end
 ```
 
+### Requirements
+
+- Elixir 1.14+
+- Erlang/OTP 24+
+- Phoenix 1.6+ (recommended)
+
 ## Quick Start
 
 ### 1. Add to Supervision Tree
@@ -197,19 +218,71 @@ sessions = Phoenix.SessionProcess.list_session()
 
 ### Session Process Helpers
 
-Inside your session process, use:
+Access session information from within your process:
 
 ```elixir
 defmodule MyApp.SessionProcess do
   use Phoenix.SessionProcess, :process
 
-  def get_session_id() do
-    # Returns the session ID for this process
+  @impl true
+  def init(_init_arg) do
+    # Get the current session ID
+    session_id = get_session_id()
+    {:ok, %{session_id: session_id, data: %{}}}
+  end
+
+  def get_current_session_id() do
     get_session_id()
   end
 end
 ```
 
+### Advanced Usage
+
+#### Rate Limiting
+The library includes built-in rate limiting to prevent session abuse:
+
+```elixir
+# Configure rate limiting (100 sessions per minute by default)
+config :phoenix_session_process,
+  rate_limit: 200,  # 200 sessions per minute
+  max_sessions: 20_000  # Maximum concurrent sessions
+```
+
+#### Custom Session State
+Store complex data structures and implement custom logic:
+
+```elixir
+defmodule MyApp.ComplexSessionProcess do
+  use Phoenix.SessionProcess, :process
+
+  @impl true
+  def init(_init_arg) do
+    {:ok, %{
+      user: nil,
+      shopping_cart: [],
+      preferences: %{},
+      activity_log: []
+    }}
+  end
+
+  @impl true
+  def handle_cast({:add_to_cart, item}, state) do
+    new_cart = [item | state.shopping_cart]
+    new_state = %{state | shopping_cart: new_cart}
+    {:noreply, new_state}
+  end
+
+  @impl true
+  def handle_call(:get_cart_total, _from, state) do
+    total = state.shopping_cart
+      |> Enum.map(& &1.price)
+      |> Enum.sum()
+    {:reply, total, state}
+  end
+end
+```
+
 ## Configuration Options
 
 | Option | Default | Description |
@@ -332,6 +405,33 @@ mix run bench/session_benchmark.exs
 
 See `bench/README.md` for detailed benchmarking guide and customization options.
 
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Setup
+
+1. Fork the repository
+2. Install dependencies: `mix deps.get`
+3. Run tests: `mix test`
+4. Run benchmarks: `mix run bench/simple_bench.exs`
+
+The project uses `devenv` for development environment management. After installation, run `devenv shell` to enter the development environment.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes and version history.
+
 ## License
 
-[MIT License](LICENSE)
+[MIT License](LICENSE)
+
+## Credits
+
+Created by [Jonathan Gao](https://github.com/gsmlg-dev)
+
+## Related Projects
+
+- [Phoenix LiveView](https://hex.pm/packages/phoenix_live_view) - Real-time user experiences
+- [Phoenix PubSub](https://hex.pm/packages/phoenix_pubsub) - Distributed PubSub
+- [Phoenix Channels](https://hexdocs.pm/phoenix/channels.html) - Real-time communication

lib/phoenix/session_process.ex

@@ -115,7 +115,32 @@ defmodule Phoenix.SessionProcess do
   end
 
   @doc """
-  Get session information including count and modules.
+  Returns all active sessions as a list of `{session_id, pid}` tuples.
+
+  ## Examples
+
+      iex> sessions = Phoenix.SessionProcess.list_session()
+      iex> is_list(sessions)
+      true
+      iex> [{session_id, pid}] = sessions
+  """
+
+  @doc """
+  Returns session statistics including total count and modules in use.
+
+  ## Examples
+
+      iex> info = Phoenix.SessionProcess.session_info()
+      iex> is_map(info)
+      true
+      iex> Map.has_key?(info, :count)
+      true
+      iex> Map.has_key?(info, :modules)
+      true
+
+  ## Returns
+
+  - `%{count: integer(), modules: list(module())}` - A map containing the total number of active sessions and a list of unique session process modules.
   """
   @spec session_info() :: %{count: integer(), modules: list(module())}
   def session_info() do
@@ -138,7 +163,23 @@ defmodule Phoenix.SessionProcess do
   end
 
   @doc """
-  Get all session IDs for a specific module.
+  Returns all session IDs for sessions managed by a specific module.
+
+  ## Examples
+
+      iex> sessions = Phoenix.SessionProcess.list_sessions_by_module(MyApp.SessionProcess)
+      iex> is_list(sessions)
+      true
+      iex> Enum.all?(sessions, &is_binary/1)
+      true
+
+  ## Parameters
+
+  - `module` - The session process module to filter by
+
+  ## Returns
+
+  - `[binary()]` - List of session IDs managed by the specified module
   """
   @spec list_sessions_by_module(module()) :: [binary()]
   def list_sessions_by_module(module) do
@@ -150,7 +191,28 @@ defmodule Phoenix.SessionProcess do
   end
 
   @doc """
-  Check if a session exists and return its PID if it does.
+  Finds a session by its ID and returns its PID if it exists.
+
+  This is different from `started?/1` in that it returns the actual PID
+  of the session process, which can be used for direct process operations.
+
+  ## Examples
+
+      iex> {:ok, pid} = Phoenix.SessionProcess.find_session("session_123")
+      iex> is_pid(pid)
+      true
+
+      iex> {:error, :not_found} = Phoenix.SessionProcess.find_session("nonexistent")
+      iex> {:error, :not_found}
+
+  ## Parameters
+
+  - `session_id` - The session ID to look up
+
+  ## Returns
+
+  - `{:ok, pid()}` - The PID of the session process if found
+  - `{:error, :not_found}` - If the session doesn't exist
   """
   @spec find_session(binary()) :: {:ok, pid()} | {:error, :not_found}
   def find_session(session_id) do
@@ -161,7 +223,28 @@ defmodule Phoenix.SessionProcess do
   end
 
   @doc """
-  Get session statistics including process count and memory usage.
+  Returns detailed session statistics including process count and memory usage.
+
+  Useful for monitoring and debugging session process performance.
+
+  ## Examples
+
+      iex> stats = Phoenix.SessionProcess.session_stats()
+      iex> is_map(stats)
+      true
+      iex> Map.has_key?(stats, :total_sessions)
+      true
+      iex> Map.has_key?(stats, :memory_usage)
+      true
+      iex> Map.has_key?(stats, :avg_memory_per_session)
+      true
+
+  ## Returns
+
+  - `%{total_sessions: integer(), memory_usage: integer(), avg_memory_per_session: integer()}` - Session statistics map
+    - `total_sessions` - Total number of active session processes
+    - `memory_usage` - Total memory usage in bytes for all session processes
+    - `avg_memory_per_session` - Average memory usage per session in bytes
   """
   @spec session_stats() :: %{
           total_sessions: integer(),