This is the v1.0 documentation, for a release that
is still in development. The API it describes is not on PyPI and can still
change.
Reading about the version you have installed? Switch to v0.x .
Version: 2026-08-11
Audience: Core maintainers, contributors, senior engineers, framework architects
Purpose: Preserve deep institutional knowledge about how Sillo works internally
# Document Description 1 Architecture Overview System layers, boundaries, component relationships, dependency graph 2 Application Lifecycle SilloApp, ASGI lifespan, startup/shutdown, state management 3 Configuration System Config class, .env loading, secret masking, environment variables 4 Type System & Encoding Core type aliases, jsonable_encoder, custom encoders, serialization
# Document Description 5 Routing System Route compilation, path matching, typed converters, groups, mounted routers 6 Middleware Pipeline BaseMiddleware, ASGI bridge, middleware chain, execution order 7 HTTP Request BaseContext, Request, body parsing, form data, file uploads 8 HTTP Response BaseResponse, JSON/File/Streaming/Redirect responses, the sillo.responses builders 9 HTTP Correctness Content negotiation, ETags, range requests, HTTP client 10 Exception Handling Exception hierarchy, ExceptionMiddleware, error handlers, status codes
# Document Description 11 Dependency Injection Depend(), Dependant tree, execution plan, resolution algorithm 12 Parameter Extraction Query/Header/Cookie/Path/Form/File markers, dual-mode validation 13 Validation System Pydantic compilation, LocationSpec, CompiledValidator, error accumulation 14 OpenAPI Generation Schema building, security schemes, documentation UIs, route iteration
# Document Description 15 Authentication Architecture useAuth, AuthenticationBackend, AuthenticationMiddleware, scheme handling 16 Auth Backends Session auth, JWT auth, API key auth, token lifecycle 17 User System UserProtocol, UserBaseModel, UserManager, SimpleUser, mixins 18 Permissions & Groups Permission model, groups, PermissionMixin, cache, authorization flow 19 Password Hashing Schemes (bcrypt/argon2/scrypt/pbkdf2), verification, password utilities
# Document Description 20 Security Middleware Shield (headers), CORS, CSRF, rate limiting strategies and backends
# Document Description 21 Record ORM - Models Model class, fields, mixins, casting, serialization, soft deletes 22 Record ORM - Queries RecordQuerySet, scopes, RecordManager, query helpers, pagination 23 Record ORM - Transactions Transaction context, savepoints, manual control, DatabaseManager 24 Record ORM - Migrations Migration commands, MigrationHelper, bridge module, console commands 25 Record ORM - Factories & Seeders Factory, FactoryBuilder, Seeder, FixtureLoader, test data generation
# Document Description 26 Work - Task System Task class, lifecycle, priorities, hooks, serialization 27 Work - Queue System Queue backends, job dispatch, workers, middleware, batches, failed jobs 28 Work - Scheduler Cron parser, triggers, scheduler manager, middleware 29 Work - Background Tasks BackgroundTask, Supervisor, restart policies, circuit breaker
# Document Description 30 Events System Event, EventEmitter, transports (memory/redis/persistent/record), propagation 31 WebSockets WebSocket state machine, consumers, channels, groups, history
# Document Description 32 Session Management SessionMiddleware, cookie/file backends, Session object, config 33 Cache System MemoryCache, RedisCache, @cache decorator, serialization, tags 34 Mail Service MailClient, SMTP, templates, attachments, config 35 Console Framework Command, Console, arguments/options/flags, output, prompts, terminal 36 Pagination Strategies (PageNumber/LimitOffset/Cursor), data handlers, paginators
# Document Description 37 Test Client Sync/async ASGI test clients, transport, WebSocket testing, helpers 38 Helpers & Utilities Files, retry, crypto, JWT, network, HTML, strings, text utilities
# Document Description 39 sillo-oauth Provider abstraction, OAuth flow, state management, PKCE, testing 40 sillo-inertia Adapter, HTML/JSON decision, props, Vite integration, version mismatch 41 sillo-start Project creation, tarball fetching, personalization, naming utilities 42 @sillo/atlas OpenAPI reference, DOM construction, API client, search, snippets 43 records-orm Standalone pypika-based ORM, backend abstraction, SQLite backend
New to the codebase? Start with 01-ARCHITECTURE-OVERVIEW.md , then read 02-APPLICATION-LIFECYCLE.md .
Debugging a production issue? Go to 47-DEBUGGING.md for symptom-based diagnosis.
Adding a new feature? Read 48-EXTENDING.md for extension patterns, then 49-CHANGE-IMPACT.md to understand blast radius.
Modifying core code? Check 49-CHANGE-IMPACT.md first to understand dependencies.
Understanding a specific subsystem? Use the table above to find the relevant document.
All technical claims in this documentation are derived from actual source code analysis of the Sillo repository at /Users/admin/sillo.build/. File paths reference the working tree as of 2026-08-11.
Key source locations:
Core framework: /Users/admin/sillo.build/core/sillo/Tests: /Users/admin/sillo.build/core/tests/OAuth: /Users/admin/sillo.build/oauth/sillo_oauth/Inertia: /Users/admin/sillo.build/inertia/sillo_inertia/Start: /Users/admin/sillo.build/start/sillo_start/Starter: /Users/admin/sillo.build/starter/Atlas: /Users/admin/sillo.build/atlas/src/records-orm: /Users/admin/sillo.build/records-orm/records_orm/ 
