# mrybs/slinn architecture

> Architecture diagram of the GitHub repository mrybs/slinn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mrybs/slinn
- Repository: https://github.com/mrybs/slinn

## Overview

##### Project type and purpose
- Slinn is an open‑source Python HTTP/HTTPS server framework.
- It provides core classes to build simple web servers, handle requests, define filters/routers, and generate HTTP responses.
- It also includes a CLI entry point (`slinn/__main__.py`, `manage.py` in templates) and project/app scaffolding templates under `slinn/templates`.

##### File structure
- Top‑level:
- setup.py, README.md, LICENSE, CLI entry (`slinn/__main__.py`)
- `slinn/` – framework package
- Inside `slinn/`:
- Core modules: `server.py`, `dispatcher.py`, `request.py`, `http_response*.py`, `filter.py` (+ specialized filters)
- Utility modules: `address.py`, `file.py`, `utils.py`
- Template scaffolds: `templates/` (example, firstrun) and `default/` (project bootstrap)
- Migration scripts: `guides/migration1xx2xx.py`
- Configuration:
- `slinn/default/project.json` – project‑level config
- `slinn/templates/*/config.json` – app‑level config

##### README for additional insights
- Describes the framework’s classes and functions (Server, Dispatcher, Address, Filter, HttpResponse variants).
- Shows how to bootstrap new projects or run standalone scripts.
- Explains CLI commands (`slinn create`, `manage.py run`, `manage.py template`).

##### Main components and their interactions
a. Components
1. CLI Interface
– `slinn/__main__.py` and `manage.py` scripts
– Commands: create project, run server, apply template
2. Server
– `Server` class listens on socket (uses `Address`)
– Accepts raw HTTP/HTTPS connections
3. Dispatcher
– Manages a registry of handlers annotated with filters
– Chooses the correct handler for each incoming `Request`
4. Request
– Parsed HTTP request object
– Contains headers, method, path, query args, cookies, files
5. Filters/Routing
– `Filter`, `LinkFilter`, `AnyFilter` define matching rules
– Applied in dispatcher to route to appropriate handler function
6. Response
– `HttpResponse` and subclasses (`HttpRedirect`, `HttpJSONResponse`, `HttpJSONAPIResponse`)
– Encapsulate payload, status, headers, cookies, produce raw HTTP response bytes
7. Utilities & Support
– `Address` for host/port resolution
– `File` wrapper for file uploads
– `utils.py` for shared helper functions
8. Templates & Scaffolding
– Provide default project/app structure (`default/`, `templates/`)
– JSON config files (`project.json`, `config.json`)

b. Relationships & data flows
1. Developer invokes CLI → scaffolds project or launches `Server`.
2. `Server.listen(Address)` opens socket and enters accept loop.
3. Incoming TCP connection → raw bytes passed to `Server`.
4. `Server` hands header/body to `Request.parse_http_header` / `parse_http_body`.
5. Completed `Request` object sent to `Dispatcher`.
6. `Dispatcher` iterates its registered handler list, using each Filter’s `check()` to match `Request`.
7. Matched handler function executes, returns an `HttpResponse` subclass.
8. `Server` calls `response.make()` to serialize to HTTP/2.0 (or HTTP/1.x) wire format.
9. Serialized response written back on the socket.

c. Architectural patterns & design principles
- Dispatcher + Filter pattern for routing.
- Modular separation: CLI, network I/O (Server), HTTP modeling (Request/Response), routing (Dispatcher/Filter), utilities.
- Template‑based scaffolding for project/app generation.
- Extensibility: add custom filters, middleware (could be introduced), response types.

d. Key technologies & libraries
- Python standard library: `socket`, `json`, `re`, `ssl`
- Packaging: `setup.py` for PyPI distribution
- No external dependencies

##### Detail without over‑engineering
- Core classes and their relationships.
- Where and how templates/config files plug into scaffolding.
- Avoid extraneous low‑level details (e.g., byte buffer sizes) unless relevant to the architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI & Scaffolding"
        CLI["CLI Interface"]:::cli
        Scaffolder["Scaffolding Script"]:::cli
    end

    subgraph "Networking & I/O"
        Server["Server"]:::netio
        Address["Address"]:::netio
        NetworkSocket["Network Socket"]:::external
    end

    subgraph "Request Modeling"
        Request["Request"]:::req
        File["File Upload Wrapper"]:::req
    end

    subgraph "Routing"
        Dispatcher["Dispatcher"]:::route
        Filter["Filter Base Class"]:::route
        AnyFilter["AnyFilter"]:::route
        LinkFilter["LinkFilter"]:::route
    end

    subgraph "Response"
        HttpResp["HttpResponse (Base)"]:::resp
        HttpRedirect["HttpRedirect"]:::resp
        HttpJSON["HttpJSONResponse"]:::resp
        HttpJSONAPI["HttpJSONAPIResponse"]:::resp
        HttpAPI["HttpAPIResponse"]:::resp
    end

    subgraph "Templates & Config"
        DefaultProj["Default Project Template"]:::tmpl
        TemplatesDir["Templates Directory"]:::tmpl
        ExampleT["Example App Template"]:::tmpl
        FirstRunT["First-Run App Template"]:::tmpl
        Migration["Migration Script"]:::tmpl
    end

    CLI -->|"invoke create/run"| Scaffolder
    CLI -->|"run server"| Server
    Scaffolder -->|"uses JSON config"| DefaultProj
    Scaffolder -->|"scaffolds apps"| TemplatesDir
    TemplatesDir --> ExampleT
    TemplatesDir --> FirstRunT
    Migration -.-> TemplatesDir

    Server -->|"listens on"| Address
    Server -->|"writes to"| NetworkSocket
    Server -->|"parses header/body"| Request
    Request -->|"contains"| File
    Server -->|"forwards request"| Dispatcher

    Dispatcher -->|"uses check()"| Filter
    Filter -->|"extended by"| AnyFilter
    Filter -->|"extended by"| LinkFilter
    Dispatcher -->|"routes via"| AnyFilter
    Dispatcher -->|"routes via"| LinkFilter
    Dispatcher -->|"returns HttpResponse"| HttpResp

    HttpResp -->|"make() serialize"| Server
    HttpRedirect -->|"inherits"| HttpResp
    HttpJSON -->|"inherits"| HttpResp
    HttpJSONAPI -->|"inherits"| HttpResp
    HttpAPI -->|"inherits"| HttpResp

    click CLI "https://github.com/mrybs/slinn/blob/master/slinn/__main__.py"
    click Scaffolder "https://github.com/mrybs/slinn/blob/master/slinn/default/manage.py"
    click Server "https://github.com/mrybs/slinn/blob/master/slinn/server.py"
    click Address "https://github.com/mrybs/slinn/blob/master/slinn/address.py"
    click Dispatcher "https://github.com/mrybs/slinn/blob/master/slinn/dispatcher.py"
    click Request "https://github.com/mrybs/slinn/blob/master/slinn/request.py"
    click Filter "https://github.com/mrybs/slinn/blob/master/slinn/filter.py"
    click AnyFilter "https://github.com/mrybs/slinn/blob/master/slinn/any_filter.py"
    click LinkFilter "https://github.com/mrybs/slinn/blob/master/slinn/link_filter.py"
    click HttpResp "https://github.com/mrybs/slinn/blob/master/slinn/http_response.py"
    click HttpRedirect "https://github.com/mrybs/slinn/blob/master/slinn/http_redirect.py"
    click HttpJSON "https://github.com/mrybs/slinn/blob/master/slinn/http_json_response.py"
    click HttpJSONAPI "https://github.com/mrybs/slinn/blob/master/slinn/http_json_api_response.py"
    click HttpAPI "https://github.com/mrybs/slinn/blob/master/slinn/http_api_response.py"
    click File "https://github.com/mrybs/slinn/blob/master/slinn/file.py"
    click TemplatesDir "https://github.com/mrybs/slinn/tree/master/slinn/templates/"
    click ExampleT "https://github.com/mrybs/slinn/tree/master/slinn/templates/example/"
    click FirstRunT "https://github.com/mrybs/slinn/tree/master/slinn/templates/firstrun/"
    click DefaultProj "https://github.com/mrybs/slinn/blob/master/slinn/default/project.json"
    click Migration "https://github.com/mrybs/slinn/blob/master/slinn/guides/migration1xx2xx.py"

    classDef cli fill:#a2fca2,stroke:#0a0,stroke-width:1px
    classDef netio fill:#a2d1fc,stroke:#045,stroke-width:1px
    classDef req fill:#fceca2,stroke:#aa8,stroke-width:1px
    classDef route fill:#fcbfa2,stroke:#a53,stroke-width:1px
    classDef resp fill:#e3b2fc,stroke:#74a,stroke-width:1px
    classDef tmpl fill:#d0d0d0,stroke:#888,stroke-width:1px
    classDef external fill:#ffffff,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
```
