Version: 2026-08-11
Audience: Core maintainers, contributors, senior engineers, framework architects
Purpose: Preserve deep institutional knowledge about how Sillo works internally
| # | Document | Description |
|---|
| 01 | Architecture Overview | System layers, boundaries, component relationships, dependency graph |
| 02 | Application Lifecycle | SilloApp, ASGI lifespan, startup/shutdown, state management |
| 03 | Configuration System | Config class, .env loading, secret masking, environment variables |
| 04 | Type System & Encoding | Core type aliases, jsonable_encoder, custom encoders, serialization |
| # | Document | Description |
|---|
| 05 | Routing System | Route compilation, path matching, typed converters, groups, mounted routers |
| 06 | Middleware Pipeline | BaseMiddleware, ASGI bridge, middleware chain, execution order |
| 07 | HTTP Request | HTTPConnection, Request, body parsing, form data, file uploads |
| 08 | HTTP Response | BaseResponse, JSON/File/Streaming/Redirect responses, Responder pattern |
| 09 | 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 | Templating | Jinja2 integration, TemplateEngine, middleware, context injection |
| 35 | Mail Service | MailClient, SMTP, templates, attachments, config |
| 36 | Console Framework | Command, Console, arguments/options/flags, output, prompts, terminal |
| 37 | Admin Panel | AdminSite, registry, routes, auth, activity log, default user model |
| 38 | Pagination | Strategies (PageNumber/LimitOffset/Cursor), data handlers, paginators |
| # | Document | Description |
|---|
| 39 | Test Client | Sync/async ASGI test clients, transport, WebSocket testing, helpers |
| 40 | Helpers & Utilities | Files, retry, crypto, JWT, network, HTML, strings, text utilities |
| # | Document | Description |
|---|
| 41 | sillo-oauth | Provider abstraction, OAuth flow, state management, PKCE, testing |
| 42 | sillo-inertia | Adapter, HTML/JSON decision, props, Vite integration, version mismatch |
| 43 | sillo-start | Project creation, tarball fetching, personalization, naming utilities |
| 44 | @sillo/atlas | OpenAPI reference, DOM construction, API client, search, snippets |
| 45 | 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/
