# Claude Code Instructions - genro-asgi

**Parent Document**: This project follows all policies from the central [meta-genro-modules CLAUDE.md](https://github.com/softwellsrl/meta-genro-modules/blob/main/CLAUDE.md)

## Project-Specific Context

### Current Status
- **Development Status**: Alpha (`Development Status :: 3 - Alpha`)
- **Version**: 0.5.0
- **Python**: >= 3.11
- **Build**: hatchling
- **Has Implementation**: Yes (core, auth, session, middleware, applications, plugins)

### Project Description

**genro-asgi** is an ASGI server and application toolkit for building web services with routing, authentication, sessions, and middleware, driven by `config.yaml`.

**Naming Convention**:
- **Package name**: `genro-asgi` (PyPI, with hyphen)
- **Import name**: `genro_asgi` (Python, with underscore)

### Dependencies

- `genro-bag` - Bag data structure (session avatar, config)
- `genro-toolbox` - SmartOptions, utilities
- `mypantry` - Config loading
- `genro-routes` - Router, RoutingClass, route decorator, FilterPlugin
- `genro-tytx` - Typed serialization (TYTX transport)
- `uvicorn` - ASGI server
- `pyyaml` - YAML config parsing
- `orjson` (optional) - Fast JSON

## Project-Specific Guidelines

### Architectural Principle: Instance Isolation

Server and apps are isolated instances, not global functions.
`del server` garbage collects everything, zero residue.

**Pattern: Dual Parent-Child Relationship**

Every child object holds a semantic reference to its parent:

```python
self.dispatcher = Dispatcher(self)

class Dispatcher:
    def __init__(self, server):
        self.server = server  # semantic name, NOT "_parent"
```

**Rule**: Code must never pollute Python's shared space:
- NO mutable global variables
- NO `global` keyword
- NO module-level singletons
- State always inside instances

### Testing Requirements

- Unit tests for all classes and functions
- Integration tests for middleware
- Type checking with mypy (strict, Python 3.11)
- Code coverage > 90%

## Project Structure

```
src/genro_asgi/
    __init__.py              # 51 public exports
    __main__.py              # CLI entry point
    types.py                 # ASGI type aliases (Scope, Message, Receive, Send, ASGIApp)
    context.py               # AsgiContext for routing
    exceptions.py            # HTTPException, WebSocket exceptions, Redirect
    lifespan.py              # Lifespan, ServerLifespan
    loader.py                # AppLoader (isolated module loading)
    request.py               # BaseRequest (ABC), HttpRequest, MsgRequest, RequestRegistry
    response.py              # Response with auto content-type, TYTX support
    resources.py             # ResourceLoader (hierarchical fallback)
    storage.py               # LocalStorage, StorageNode
    websocket.py             # WebSocket, WebSocketState
    applications/
        asgi_application.py  # Base app class (RoutingClass + resources + mount_name)
        openapi_application.py  # OpenAPI schema + Swagger UI
        mcp_application.py   # MCP (Model Context Protocol) endpoints
        resources/           # HTML templates for application pages
    authentication/          # Backward-compatible (logic in server.auth_mixin)
    datastructures/          # Address, Headers, QueryParams, State, URL
    executors/               # BaseExecutor, LocalExecutor, ExecutorRegistry
    middleware/              # Auto-discovery system, 9 middleware types + base
    routers/                 # StaticRouter
    server/
        server.py            # AsgiServer (central coordinator)
        server_config.py     # ServerConfig (YAML loading)
        dispatcher.py        # Dispatcher (request routing + lifecycle)
        auth_mixin.py        # BasicAuthMixin
        handler_executor.py  # HandlerExecutor
        server_app/          # ServerApplication (_server/ meta endpoints)
    session/                 # Session, Avatar, MemorySessionStore
    sys_applications/        # Mountable sys_apps (genro_api, login_page, plugin_config, swagger)
    utils/                   # ServerBinder, AsgiServerEnabler
    wsx/                     # WSX protocol (WebSocket eXtended)
contrib/
    genropy_asgi/            # GenroPy integration (GenropyAsgiServer, db_registry)
tests/                       # 25 test files
docs/architecture/           # Architecture docs (00-overview through 09-auth-context)
```

## Design Decisions

1. **Type-safe**: Full type hints, mypy strict mode
2. **ASGI-compliant**: Follow ASGI spec strictly
3. **Apache 2.0 license**: Permissive, business-friendly
4. **Config-driven**: Server configuration via YAML with programmatic override
5. **Plugin system**: FilterPlugin for auth_tags/env_capabilities filtering

## Quick Reference

| Area | Key Files |
|------|-----------|
| Server core | server/server.py, server/dispatcher.py, server/server_config.py |
| Applications | applications/asgi_application.py, applications/openapi_application.py |
| Request/Response | request.py, response.py |
| Auth/Session | server/auth_mixin.py, session/, middleware/auth.py, middleware/session.py |
| Routing | context.py, routers/static_router.py |
| Middleware | middleware/__init__.py (auto-discovery + chain builder) |
| Meta endpoints | server/server_app/ (/_server/ routes) |

## Relationship with Genro Modules

genro-asgi is part of the **Genro Modules** ecosystem:
- Depends on genro-bag, genro-toolbox, genro-routes, genro-tytx, mypantry
- Provides ASGI server foundation for GenroPy applications
- `contrib/genropy_asgi/` bridges to GenroPy (GnrApp, db_registry)
- Can be used standalone without GenroPy

---

**All general policies (language, git authorship, coding style, development workflow, etc.) are inherited from the parent document.**
