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 “. File paths reference the working tree as of 2026-08-11.
Key source locations:
- Core framework:
core/sillo/
- Tests:
core/tests/
- OAuth:
oauth/sillo_oauth/
- Inertia:
inertia/sillo_inertia/
- Start:
start/sillo_start/
- Starter:
starter/
- Atlas:
atlas/src/
- records-orm:
records-orm/records_orm/
