otto 2.0.0.pre2 → 2.0.0.pre7

data/Gemfile.lock

@@ -1,18 +1,21 @@
 PATH
   remote: .
   specs:
-    otto (2.0.0.pre2)
+    otto (2.0.0.pre7)
+      concurrent-ruby (~> 1.3, < 2.0)
       facets (~> 3.1)
+      ipaddr (~> 1, < 2.0)
       logger (~> 1, < 2.0)
       loofah (~> 2.20)
       rack (~> 3.1, < 4.0)
       rack-parser (~> 0.7)
-      rexml (>= 3.3.6)
+      rexml (~> 3.4)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
+    benchmark (0.5.0)
     bigdecimal (3.2.3)
     concurrent-ruby (1.3.5)
     crass (1.0.6)
@@ -21,15 +24,45 @@ GEM
       irb (~> 1.10)
       reline (>= 0.3.8)
     diff-lcs (1.6.2)
-    erb (5.0.2)
+    dry-configurable (1.3.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
+    dry-core (1.1.0)
+      concurrent-ruby (~> 1.0)
+      logger
+      zeitwerk (~> 2.6)
+    dry-inflector (1.2.0)
+    dry-initializer (3.2.0)
+    dry-logic (1.6.0)
+      bigdecimal
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.1)
+      zeitwerk (~> 2.6)
+    dry-schema (1.14.1)
+      concurrent-ruby (~> 1.0)
+      dry-configurable (~> 1.0, >= 1.0.1)
+      dry-core (~> 1.1)
+      dry-initializer (~> 3.2)
+      dry-logic (~> 1.5)
+      dry-types (~> 1.8)
+      zeitwerk (~> 2.6)
+    dry-types (1.8.3)
+      bigdecimal (~> 3.0)
+      concurrent-ruby (~> 1.0)
+      dry-core (~> 1.0)
+      dry-inflector (~> 1.0)
+      dry-logic (~> 1.4)
+      zeitwerk (~> 2.6)
+    erb (5.1.1)
     facets (3.1.0)
     hana (1.3.7)
     io-console (0.8.1)
+    ipaddr (1.2.7)
     irb (1.15.2)
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.15.1)
+    json (2.15.2)
     json_schemer (2.4.0)
       bigdecimal
       hana (~> 1.3)
@@ -41,7 +74,7 @@ GEM
     loofah (2.24.1)
       crass (~> 1.0.2)
       nokogiri (>= 1.12.0)
-    minitest (5.25.5)
+    minitest (5.26.0)
     nokogiri (1.18.10-aarch64-linux-gnu)
       racc (~> 1.4)
     nokogiri (1.18.10-aarch64-linux-musl)
@@ -59,22 +92,22 @@ GEM
     nokogiri (1.18.10-x86_64-linux-musl)
       racc (~> 1.4)
     parallel (1.27.0)
-    parser (3.3.9.0)
+    parser (3.3.10.0)
       ast (~> 2.4.1)
       racc
     pastel (0.8.0)
       tty-color (~> 0.5)
-    pp (0.6.2)
+    pp (0.6.3)
       prettyprint
     prettier_print (1.2.1)
     prettyprint (0.2.0)
-    prism (1.5.2)
+    prism (1.6.0)
     psych (5.2.6)
       date
       stringio
     racc (1.8.1)
-    rack (3.2.2)
-    rack-attack (6.7.0)
+    rack (3.2.4)
+    rack-attack (6.8.0)
       rack (>= 1.0, < 4)
     rack-parser (0.7.0)
       rack
@@ -85,27 +118,34 @@ GEM
     rainbow (3.1.1)
     rbs (3.9.5)
       logger
-    rdoc (6.14.2)
+    rdoc (6.15.0)
       erb
       psych (>= 4.0.0)
+      tsort
+    reek (6.5.0)
+      dry-schema (~> 1.13)
+      logger (~> 1.6)
+      parser (~> 3.3.0)
+      rainbow (>= 2.0, < 4.0)
+      rexml (~> 3.1)
     regexp_parser (2.11.3)
     reline (0.6.2)
       io-console (~> 0.5)
     rexml (3.4.4)
-    rspec (3.13.1)
+    rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.5)
+    rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.5)
+    rspec-mocks (3.13.6)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.5)
-    rubocop (1.81.1)
+    rspec-support (3.13.6)
+    rubocop (1.81.7)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -119,10 +159,10 @@ GEM
     rubocop-ast (1.47.1)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
-    rubocop-performance (1.26.0)
+    rubocop-performance (1.26.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
-      rubocop-ast (>= 1.44.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
     rubocop-rspec (3.7.0)
       lint_roller (~> 1.1)
       rubocop (~> 1.72, >= 1.72.1)
@@ -130,7 +170,7 @@ GEM
       lint_roller (~> 1.1)
       rubocop (~> 1.72, >= 1.72.1)
       rubocop-ast (>= 1.44.0, < 2.0)
-    ruby-lsp (0.26.1)
+    ruby-lsp (0.26.2)
       language_server-protocol (~> 3.17.0)
       prism (>= 1.2, < 2.0)
       rbs (>= 3, < 5)
@@ -140,21 +180,24 @@ GEM
     stringio (3.1.7)
     syntax_tree (6.3.0)
       prettier_print (>= 1.2.0)
-    tryouts (3.6.0)
-      concurrent-ruby (~> 1.0)
+    tryouts (3.7.1)
+      concurrent-ruby (~> 1.0, < 2)
       irb
       minitest (~> 5.0)
       pastel (~> 0.8)
       prism (~> 1.0)
-      rspec (~> 3.0)
+      rspec (>= 3.0, < 5.0)
       tty-cursor (~> 0.7)
       tty-screen (~> 0.8)
+    tsort (0.2.0)
     tty-color (0.6.0)
     tty-cursor (0.7.1)
     tty-screen (0.8.2)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
     unicode-emoji (4.1.0)
+    user_agent_parser (2.20.0)
+    zeitwerk (2.7.3)
 
 PLATFORMS
   aarch64-linux-gnu
@@ -167,21 +210,24 @@ PLATFORMS
   x86_64-linux-musl
 
 DEPENDENCIES
+  benchmark
   debug
   json_schemer
   otto!
   rack-attack
   rack-test
   rackup
+  reek (~> 6.5)
   rspec (~> 3.13)
-  rubocop (~> 1.81.1)
+  rubocop (~> 1.81.7)
   rubocop-performance
   rubocop-rspec
   rubocop-thread_safety
   ruby-lsp
   stackprof
   syntax_tree
-  tryouts (~> 3.6.0)
+  tryouts (~> 3.7.1)
+  user_agent_parser (~> 2.18)
 
 BUNDLED WITH
    2.7.1

data/README.md

@@ -2,7 +2,7 @@
 
 **Define your rack-apps in plain-text with built-in security.**
 
-> **v2.0.0-pre1 Available**: This pre-release includes major improvements to middleware management and test coverage. See [changelog](CHANGELOG.rst) and [migration guide](docs/migrating/v2.0.0-pre1.md) for upgraders.
+> **v2.0.0-pre6 Available**: This pre-release includes major improvements to middleware management, logging, and request callback handling. See [changelog](CHANGELOG.rst) for details and upgrade notes.
 
 ![Otto mascot](public/img/otto.jpg "Otto - All Rack, no Pinion")
 
@@ -13,6 +13,14 @@ $ cd myapp && ls
 config.ru app.rb routes
 ```
 
+## Why Otto?
+
+- **Security by Default**: Automatic IP masking for public addresses, user agent anonymization, CSRF protection, and input validation
+- **Privacy First**: Masks public IPs, strips user agent versions, provides country-level geo-location only—no external APIs needed
+- **Simple Routing**: Define routes in plain-text files with zero configuration overhead
+- **Built-in Authentication**: Multiple strategies including API keys, tokens, role-based access, and custom implementations
+- **Developer Friendly**: Works with any Rack server, minimal dependencies, easy testing and debugging
+
 ## Routes File
 ```
 # routes
@@ -76,6 +84,22 @@ app = Otto.new("./routes", {
 
 Security features include CSRF protection, input validation, security headers, and trusted proxy configuration.
 
+## Privacy by Default
+
+Otto automatically masks public IP addresses and anonymizes user agents to comply with GDPR, CCPA, and other privacy regulations:
+
+```ruby
+# Public IPs are automatically masked (203.0.113.9 → 203.0.113.0)
+# Private IPs are NOT masked by default (127.0.0.1, 192.168.x.x, 10.x.x.x)
+app = Otto.new("./routes")
+
+# User agents: versions stripped for privacy
+# Geo-location: country-level only, no external APIs or databases
+# IP hashing: daily-rotating hashes enable analytics without tracking
+```
+
+Private and localhost IPs are exempted by default for development convenience, but this behavior can be customized via `configure_ip_privacy()` method. Geolocation uses CDN headers (Cloudflare, AWS, etc.) with fallback to IP ranges—no external services required. See [CLAUDE.md](CLAUDE.md) for detailed configuration options.
+
 ## Internationalization Support
 
 Otto provides built-in locale detection and management:
@@ -132,6 +156,24 @@ end
 
 The locale helper checks multiple sources in order of precedence and validates against your configured locales.
 
+## Examples
+
+Otto includes comprehensive examples demonstrating different features:
+
+- **[Basic Example](examples/basic/)** - Get your first Otto app running in minutes
+- **[Advanced Routes](examples/advanced_routes/)** - Response types, CSRF exemption, logic classes, and namespaced routing
+- **[Authentication Strategies](examples/authentication_strategies/)** - Token, API key, and role-based authentication
+- **[Security Features](examples/security_features/)** - CSRF protection, input validation, file uploads, and security headers
+- **[MCP Demo](examples/mcp_demo/)** - JSON-RPC 2.0 endpoints for CLI automation and integrations
+
+### Standalone Tutorials
+
+- **[Error Handler Registration](examples/error_handler_registration.rb)** - Prevent 500 errors for expected business exceptions
+- **[Logging Improvements](examples/logging_improvements.rb)** - Structured logging with automatic timing
+- **[Geo-location Extension](examples/simple_geo_resolver.rb)** - Extending geo-location with custom resolvers
+
+See the [examples/](examples/) directory for more.
+
 ## Requirements
 
 - Ruby 3.2+
@@ -143,6 +185,12 @@ The locale helper checks multiple sources in order of precedence and validates a
 gem install otto
 ```
 
+## Documentation
+
+- **[CLAUDE.md](CLAUDE.md)** - Comprehensive developer guidance covering authentication architecture, configuration freezing, IP privacy, structured logging, and multi-app patterns
+- **[docs/](docs/)** - Technical guides and migration guides
+- **[CHANGELOG.rst](CHANGELOG.rst)** - Version history, breaking changes, and upgrade notes
+
 ## AI Development Assistance
 
 Version 1.2.0's security features were developed with AI assistance:

data/changelog.d/20251103_235431_delano_86_improve_error_logging.rst

@@ -0,0 +1,15 @@
+Added
+-----
+
+- Error handler registration system for expected business logic errors. Register handlers with ``otto.register_error_handler(ErrorClass, status: 404, log_level: :info)`` to return proper HTTP status codes and avoid logging expected errors as 500s with backtraces. Supports custom response handlers via blocks for complete control over error responses.
+
+Changed
+-------
+
+- Backtrace logging now always logs at ERROR level (was DEBUG) with sanitized file paths for security. Backtraces for unhandled 500 errors are always logged regardless of ``OTTO_DEBUG`` setting, with paths sanitized to prevent exposing system information (project files show relative paths, gems show ``[GEM] name-version/path``, Ruby stdlib shows ``[RUBY] filename``).
+- Increased backtrace limit from 10 to 20 lines for critical errors to provide better debugging context.
+
+AI Assistance
+-------------
+
+- Implemented error handler registration architecture with comprehensive test coverage (17 test cases) using sequential thinking to work through security implications and design decisions. AI assisted with path sanitization strategy, error classification patterns, and ensuring backward compatibility with existing error handling.

data/changelog.d/20251109_025012_claude_fix_backtrace_sanitization.rst

@@ -0,0 +1,37 @@
+.. Changed in: otto
+.. Fixes issue:
+
+Improved backtrace sanitization security and readability
+---------------------------------------------------------
+
+**Security Enhancements:**
+
+- Fixed bundler gem path detection to correctly sanitize git-based gems
+- Now properly handles nested gem paths like ``/gems/3.4.0/bundler/gems/otto-abc123/``
+- Strips git hash suffixes from bundler gems (``otto-abc123def456`` → ``otto``)
+- Removes version numbers from regular gems (``rack-3.2.4`` → ``rack``)
+- Prevents exposure of absolute paths, usernames, and project names in logs
+
+**Improvements:**
+
+- Bundler gems now show as ``[GEM] otto/lib/otto/route.rb:142`` instead of ``[GEM] 3.4.0/bundler/gems/...``
+- Regular gems show cleaner output: ``[GEM] rack/lib/rack.rb:20`` instead of ``[GEM] rack-3.2.4/lib/rack.rb:20``
+- Multi-hyphenated gem names handled correctly (``active-record-import-1.5.0`` → ``active-record-import``)
+- Better handling of version-only directory names in gem paths
+
+**Documentation:**
+
+- Added comprehensive backtrace sanitization section to CLAUDE.md
+- Documented security guarantees and sanitization rules
+- Added examples showing before/after path transformations
+- Created comprehensive test suite for backtrace sanitization
+
+**Rationale:**
+
+Raw backtraces expose sensitive information:
+- Usernames (``/Users/alice/``, ``/home/admin/``)
+- Project structure and internal organization
+- Gem installation paths and Ruby versions
+- System architecture details
+
+This improvement ensures all backtraces are sanitized automatically, preventing accidental leakage of sensitive system information while maintaining readability for debugging.

data/docs/.gitignore

@@ -2,3 +2,4 @@
 !.gitignore
 !migrating/
 !migrating/*.md
+!ipaddr-encoding-quirk.md

data/docs/ipaddr-encoding-quirk.md

@@ -0,0 +1,34 @@
+# IPAddr#to_s Encoding Quirk in Ruby 3
+
+Ruby's `IPAddr#to_s` returns inconsistent encodings: IPv4 addresses use US-ASCII, IPv6 addresses use UTF-8.
+
+## Behavior
+
+```ruby
+IPAddr.new('192.168.1.1').to_s.encoding  # => #<Encoding:US-ASCII>
+IPAddr.new('::1').to_s.encoding          # => #<Encoding:UTF-8>
+```
+
+## Cause
+
+Different string construction in IPAddr's `_to_string` method:
+
+- **IPv4**: `Array#join('.')` → US-ASCII optimization
+- **IPv6**: `String#%` → UTF-8 default
+
+## Impact
+
+- Rack expects UTF-8 strings
+- Mixed encodings cause `Encoding::CompatibilityError`
+- String operations fail on encoding mismatches
+
+## Solution
+
+Use `force_encoding('UTF-8')` instead of `encode('UTF-8')`:
+
+- IP addresses contain only ASCII characters
+- ASCII bytes are identical in US-ASCII and UTF-8
+- `force_encoding` changes label only (O(1))
+- `encode` creates new string (O(n))
+
+This ensures consistent UTF-8 encoding across all IP strings.

data/docs/migrating/v2.0.0-pre2.md

@@ -27,12 +27,6 @@ if strategy_result.is_a?(Otto::Security::Authentication::StrategyResult)
   # handle success
 end
 
-# Or for middleware - FailureResult indicates failure
-if strategy_result.is_a?(Otto::Security::Authentication::FailureResult)
-  # handle failure
-else
-  # handle success
-end
 ```
 
 ### 2. New Semantic Distinction
@@ -116,7 +110,7 @@ session['authenticated_at']  # Timestamp
 **Optional session keys:**
 ```ruby
 session['email']            # User email
-session['ip_address']       # Client IP
+session['ip_address']       # Client IP (masked by default via IPPrivacyMiddleware)
 session['user_agent']       # Client UA
 session['locale']           # User locale
 ```
@@ -140,7 +134,7 @@ class Controller::Base
       session: session,
       user: cust,
       auth_method: 'session',  # Hardcoded - loses semantic meaning
-      metadata: { ip: req.client_ipaddress }
+      metadata: { ip: req.masked_ip }  # Uses masked IP (privacy by default)
     )
   end
 end
@@ -148,10 +142,10 @@ end
 
 **Correct approach:**
 ```ruby
-# GOOD - Use middleware-provided result
+# GOOD - Use RouteAuthWrapper-provided result
 class Controller::Base
   def strategy_result
-    req.env['otto.strategy_result']  # Created by AuthenticationMiddleware
+    req.env['otto.strategy_result']  # Created by RouteAuthWrapper
   end
 end
 
@@ -188,7 +182,6 @@ expect(result).to be_failure
 
 # After
 expect(result).to be_a(Otto::Security::Authentication::StrategyResult)
-expect(result).to be_a(Otto::Security::Authentication::FailureResult)
 ```
 
 ## Architecture Clarifications
@@ -196,13 +189,13 @@ expect(result).to be_a(Otto::Security::Authentication::FailureResult)
 ### When StrategyResult is Created
 
 1. **Routes WITH `auth=...` requirement:**
-   - Strategy executes
-   - Returns `StrategyResult` (success) or `FailureResult` (failure)
-   - Middleware converts `FailureResult` to anonymous `StrategyResult` + 401 response
+   - RouteAuthWrapper executes strategy
+   - Always returns `StrategyResult` (success or failure)
+   - RouteAuthWrapper returns 401/302 response on `AuthFailure`
 
 2. **Routes WITHOUT `auth=...` requirement:**
-   - Middleware creates anonymous `StrategyResult`
-   - Sets `auth_method: 'anonymous'`
+   - No RouteAuthWrapper wrapping
+   - No `StrategyResult` created (routes without auth don't need it)
 
 3. **Auth app (Roda) routes:**
    - Manually creates `StrategyResult` for Logic class compatibility
@@ -213,7 +206,7 @@ expect(result).to be_a(Otto::Security::Authentication::FailureResult)
 **Multi-app setup (Auth + Core + API):**
 - **Shared:** Session middleware, Redis session, Logic classes, Customer model
 - **Auth app:** Creates StrategyResult manually, uses Roda routing
-- **Core/API apps:** StrategyResult from AuthenticationMiddleware
+- **Core/API apps:** StrategyResult from RouteAuthWrapper
 - **Integration:** Pure session-based, no direct code calls between apps
 
 ## Testing Your Migration
@@ -339,7 +332,7 @@ middleware.add_with_position(
 
 Review the comprehensive inline documentation in:
 - `lib/otto/security/authentication/strategy_result.rb` (lines 1-90) - Auth semantics
-- `lib/otto/security/authentication/authentication_middleware.rb` - Auth middleware
+- `lib/otto/security/authentication/route_auth_wrapper.rb` - Auth handler wrapper
 - `lib/otto/env_keys.rb` - Complete env key registry
 
 The documentation includes detailed usage patterns, session contracts, and examples for common scenarios.

data/examples/advanced_routes/README.md

@@ -1,33 +1,150 @@
 # Otto - Advanced Routes Example
 
-This example demonstrates the advanced routing syntax features available in Otto, such as response type negotiation, CSRF exemptions, and routing to logic classes.
+This example demonstrates advanced routing features in Otto, including response type negotiation, CSRF exemptions, logic classes, and namespaced routing.
+
+## What You'll Learn
+
+- How to define response types (JSON, view, redirect) in routes
+- Using logic classes to encapsulate business logic
+- CSRF exemption for APIs and webhooks
+- Routing to namespaced classes with complex hierarchies
+- Custom route parameters for flexible routing
+- How Otto handles multiple controllers and modules
 
 ## Project Structure
 
-The example is structured to separate concerns, making it easier to navigate:
+The example is organized to separate concerns:
 
--   `config.ru`: The main Rackup file that loads and runs the Otto application.
--   `routes`: A comprehensive file demonstrating various advanced routing syntaxes. This file serves as a good reference.
--   `app.rb`: A simple loader that requires all controller and logic files.
--   `app/controllers/`: Contains the `RoutesApp` class and other namespaced controller modules that handle incoming requests.
--   `app/logic/`: Contains various "Logic Classes". These are special classes that can be routed to directly, encapsulating business logic for a specific route. They are organized into namespaces to show how Otto handles complex class names.
--   `run.rb`, `puma.rb`, `test.rb`: Alternative ways to run or test the application.
+- `config.ru`: Rack configuration that loads and runs the Otto application
+- `routes`: Comprehensive reference for advanced routing syntax
+- `app.rb`: Loader that requires all controller and logic files
+- `app/controllers/`: Handler classes (`RoutesApp`, namespaced controllers)
+- `app/logic/`: Business logic classes (simple, nested, namespaced)
+- `run.rb`, `puma.rb`, `test.rb`: Alternative server/test runners
 
 ## Key Features Demonstrated
 
--   **Response Types:** Defining `response=json`, `response=view`, etc., directly in the `routes` file.
--   **CSRF Exemption:** Using `csrf=exempt` for APIs or webhooks.
--   **Logic Classes:** Routing directly to a class (e.g., `GET /logic/simple SimpleLogic`). Otto automatically instantiates it and calls its `process` method.
--   **Namespaced Targets:** Routing to deeply namespaced classes and modules (e.g., `GET /logic/v2/dashboard V2::Logic::Dashboard`).
--   **Custom Parameters:** Adding arbitrary key-value parameters to a route for custom logic.
+### Response Types
+Define how responses are formatted directly in routes:
+```
+GET  /api/users        UserController#list      response=json
+GET  /page             PageController#show      response=view
+GET  /old-url          PageController#new-url   response=redirect
+```
+
+### Logic Classes
+Route to specialized classes that encapsulate business logic:
+```
+GET  /calculate        DataProcessor   # Otto auto-instantiates and calls #process
+GET  /report           ReportGenerator # Same pattern
+```
+
+### CSRF Exemption
+Mark routes that don't need CSRF tokens (APIs, webhooks):
+```
+POST /api/webhook      WebhookHandler#receive   csrf=exempt
+```
+
+### Namespaced Routing
+Handle complex class hierarchies naturally:
+```
+GET  /v2/dashboard     V2::Logic::Dashboard
+GET  /admin/panel      Admin::Panel#dashboard
+```
+
+### Custom Parameters
+Add arbitrary key-value pairs for flexible routing:
+```
+GET  /admin            AdminPanel#dashboard     role=admin
+```
+
+## How to Run
+
+### Using rackup (recommended)
+
+```sh
+cd examples/advanced_routes
+rackup config.ru
+```
+
+### Using alternative runners
+
+```sh
+ruby run.rb   # Basic rackup
+ruby puma.rb  # Using puma server
+ruby test.rb  # For testing
+```
+
+The application will be running at `http://localhost:9292`.
+
+## Testing Routes
+
+Use curl to test the different routes:
+
+```sh
+# JSON response
+curl http://localhost:9292/json/test
+
+# View response
+curl http://localhost:9292/view/test
+
+# Logic class routing
+curl http://localhost:9292/logic/simple
+
+# Namespaced routing
+curl http://localhost:9292/logic/v2/dashboard
+
+# Custom parameters
+curl "http://localhost:9292/custom?role=admin"
+```
+
+## Expected Output
+
+```
+Listening on 127.0.0.1:9292, CTRL+C to stop
+
+[JSON response]
+GET /json/test 200 OK
+Content-Type: application/json
+{"status": "success", "data": {...}}
+
+[Logic class routing]
+GET /logic/simple 200 OK
+{"processed": true, "input": "test"}
+
+[Namespaced routing]
+GET /logic/v2/dashboard 200 OK
+{"version": "2.0", "dashboard": {...}}
+```
+
+## File Structure Details
+
+### Routes File
+The `routes` file is extensively commented to explain each feature:
+- Response type specification
+- CSRF exemption for APIs
+- Logic class routing syntax
+- Namespaced class resolution
+- Custom parameter examples
+
+### Controllers (`app/controllers/`)
+- `RoutesApp`: Main controller with basic handlers
+- Namespaced modules: Demonstrate complex class hierarchies
+- Handlers return appropriate responses (JSON, HTML, redirects)
+
+### Logic Classes (`app/logic/`)
+- Simple classes: Basic business logic
+- Nested classes: Show how Otto handles namespace resolution
+- Parameterized logic: Demonstrate custom route parameters
 
-## Running the Example
+## Next Steps
 
-1.  Make sure you have the necessary gems installed (`bundle install`).
-2.  Run the application from the root of the `otto` project:
+- Review the `routes` file for syntax reference
+- Examine handler methods to see request/response patterns
+- Check logic classes for business logic encapsulation patterns
+- Explore [Authentication](../authentication_strategies/) for protecting routes
+- See [Security Features](../security_features/) for CSRF, validation, file uploads
 
-    ```sh
-    rackup examples/advanced_routes/config.ru
-    ```
+## Further Reading
 
-3.  The application will be running at `http://localhost:9292`. You can use `curl` or your browser to test the various routes defined in the `routes` file.
+- [CLAUDE.md](../../CLAUDE.md) - Comprehensive developer guidance