Project Structure
Caspian keeps route UI and route behavior together in Python, reusable rendered
UI in src/components/, and shared
application services in src/lib/.
Application source
Routes, layouts, components, helpers, styles, auth policy, and optional
feature integrations live under src/.
Framework runtime
The installed casp package supplies routing,
layouts, components, RPC, auth, validation, caching, and streaming.
Canonical workspace
caspian.config.json # feature gates and generator settings main.py # FastAPI app, middleware, sockets, runtime wiring src/ app/ layout.py # root document shell and metadata index.py # route page, data, metadata, and actions loading.py # optional synchronous loading UI not_found.py # optional global 404 page error.py # optional global error page globals.css # global styles dashboard/ layout.py # shared /dashboard shell settings/ index.py # /dashboard/settings components/ # reusable Python x-* components lib/ # shared services, auth, validators, integrations public/ # browser-served assets and runtime bundles settings/ # development, checks, route/component inventories tests/ # application and tooling tests
Ownership rules
Route modules
src/app/**/index.py owns first-render data, route metadata, redirects, validation, and route-local RPC or upload actions. Its page() returns readable inline markup through html(r"""...""").
Component modules
src/components/ contains focused single-root Python components. Import each child component in the module that authors its <x-*> tag.
Shared application code
src/lib/ is for services used by multiple routes or components. Auth policy belongs in src/lib/auth/auth_config.py; enabled integrations receive their own focused directories.
Feature configuration
caspian.config.json decides whether Tailwind, Prisma, MCP, WebSockets, TypeScript, and backend-only surfaces are present. Generated files follow those gates.
Generated and installed surfaces
Treat settings/component-map.json,
settings/files-list.json, compiled public assets,
caches, and bytecode as generated artifacts. Read the installed
.venv/Lib/site-packages/casp/ runtime when a
framework behavior needs confirmation; application changes stay in app-owned files.