Source-to-feature guide
Core Runtime Map
Find the file that owns a Caspian behavior before changing it. Application
code is the source of truth for the current project; the installed
casp package is the source of truth for framework internals.
1 · ENABLEMENT
caspian.config.json
Feature gates decide which optional surfaces are generated and available.
2 · APPLICATION
main.py + src/**
Routes, policies, components, actions, services, and application wiring live here.
3 · FRAMEWORK
site-packages/casp/**
Inspect the installed package when the behavior is owned by Caspian itself.
Feature ownership
| Feature | App entry point | Runtime owner | Guide |
|---|---|---|---|
| Routing and layouts | src/app/**/index.py, layout.py | main.py, casp.layout | Routing |
| Components and x-* tags | src/components/** | component_decorator, components_compiler | Components |
| RPC and streaming | route-local @rpc() actions | casp.rpc, casp.streaming | RPC |
| Auth and security | src/lib/auth/auth_config.py, main.py | casp.auth, runtime_security | Authentication |
| State, cache, validation | routes and RPC boundaries | state_manager, cache_handler, validate | State |
| API endpoints | src/app/**/route.py | casp.api_routes, main.py | API Routes |
| Errors and request ids | error.py boundaries, raise HttpError | casp.errors, render_error_response | Error Handling |
| Authorization | src/lib/auth/policies.py | casp.authorization | Authorization |
| Application middleware | src/middleware.py | casp.request_pipeline | Request Pipeline |
| Data cache | cache.remember(...) | casp.cache | Caching |
| Jobs and scheduling | src/lib/jobs.py, src/lib/schedule.py | casp.jobs, casp.schedule | Background Jobs |
| Logs, probes, metrics | record(...), src/lib/readiness.py | casp.observability | Observability |
| Maintenance mode | npm run down/up, src/app/maintenance.py | casp.maintenance | Maintenance |
| Localization | src/locales/*.json, t(...) | casp.i18n | Localization |
| Named sockets | @socket(), src/lib/websocket/** | sockets.py + main.py wiring | WebSockets |
| Prisma and MCP | prisma/**, src/lib/prisma/**, src/lib/mcp/** | generated clients and app-owned server | Database |
Request path
- 01Request id, security headers, public files, request logs, maintenance mode, rate limits, body limits, sessions, CSRF, auth, the app's
src/middleware.pypipeline, and RPC run through the middleware stack. - 02Route registration injects path parameters, matching query parameters, and the request only when declared.
- 03Components and nested layouts render, scripts transform, and component roots are deferred into inert templates.
- 04PulsePoint materializes the roots, evaluates owned scripts, and mounts the reactive page.
Debug in the right layer
-
Wrong route or layout data: start in
src/app/**. -
Missing component props: inspect
get_attributes(...)and the rendered root. -
Unexpected auth, headers, or public files: inspect
main.pyandruntime_security.py. - Browser render or navigation behavior: use the PulsePoint runtime map.
Application time is a core contract
Use casp.app_time for application calendar work.
APP_TIMEZONE resolves once at boot, stored timestamps stay UTC,
and local-day queries use half-open [start, end) bounds.
Avoid bare datetime.now() in application code.