Project Structure

Caspian follows a convention-over-configuration approach. Understanding the directory layout is key to building scalable, async applications.

Top-Level Overview

Your project is organized into three main areas: the Application Source (src), the Framework Utilities (utils), and the Database (prisma).

src/

The heart of your application. Contains your routes, pages, styles, and libraries.

utils/

The framework engine room. Contains authentication, RPC handling, database clients, and Pydantic models.

prisma/

Database schema and seed scripts. This is where you define your data models.

public/

Static assets like images, fonts, and compiled JS/CSS. Files here are served directly by Starlette/FastAPI.

Directory Breakdown

  • main.py
  • caspian.config.json
  • prisma/
    • schema.prisma // Database models
    • seed.ts // Data seeding script
  • src/
    • app/ // File-based routing
      • layout.html // Root layout
      • index.py // Backend logic for "/"
      • index.html // Template for "/"
      • globals.css
    • lib/ // Shared helpers & UI libraries
  • utils/
    • auth.py // Authentication logic
    • rpc.py // Server Actions handler
    • validate.py // Pydantic Models
    • prisma/ // Generated Python client

Key Files

src/app/index.py

The backend logic for your pages. This is where you define RPC functions using @rpc and fetch initial data asynchronously.

src/app/index.html

The visual template for your pages. This file supports standard HTML, PulsePoint directives (pp-for), and component imports.

utils/auth.py

Central configuration for the authentication system. Define protected routes, user roles, and sign-in redirects here using FastAPI dependencies.