Foundations

The bases/ directory contains shared infrastructure used across all feature modules.

Configuration (bases/conf)

Runtime configuration is stored in the core_conf database table instead of environment variables. This enables runtime changes without redeployment.

CoreConf Trait

pub trait CoreConf {
    fn from_row(row: schemas::core_conf::Model) -> Self;
}

Each module defines a config struct that implements CoreConf, selecting only the columns it needs:

Config Type	Module	Fields
TwilioCoreConf	Twilio	twilio_main_sid, twilio_main_token
OpenAICoreConf	OpenAI	openai_api_key
GeminiCoreConf	Gemini	google_project_id, google_location
ResendCoreConf	Email	resend_api_key
EmailAddressesCoreConf	Email	email_domain, email_user_admin

Loading is a single generic call:

let twilio_conf = get_core_conf::<TwilioCoreConf>().await?;
let openai_conf = get_core_conf::<OpenAICoreConf>().await?;

Tip

To add a new config type: create a struct, implement CoreConf, and call get_core_conf::<YourType>(). No registration needed.

Database (bases/db)

Database access uses SeaORM with PostgreSQL (Supabase).

let db = db_client().await?;

db_client() reads DATABASE_URL from the environment and returns a sea_orm::DatabaseConnection. SeaORM manages connection pooling internally via sqlx.

All entity schemas live in src/schemas/ and are accessed as crate::schemas::<table>::Entity.

Authentication (bases/auth)

Auth is built on Supabase Auth with cookie-based sessions.

Session Extractor

Use Session as an axum extractor to require authentication:

pub struct Session {
    pub id: Uuid,
    pub user: User,           // { id, name }
    pub organization: Organization,  // { id, name }
}

Rejects with 401 Unauthorized if the caller is not authenticated.

AuthState Extractor

Use AuthState when you need to handle both authenticated and unauthenticated requests:

pub enum AuthState {
    MissingCookieHeader,
    InvalidCookieHeader,
    MissingSessionTokenCookie,
    InvalidSessionToken,
    ExpiredSession,
    ActiveSession(Session),
}

Auth Flow

1. Parse Cookie header → extract session_token
2. Look up session in database by token
3. Check expiry
4. Load associated User and Organization
5. Return AuthState::ActiveSession(Session { ... }) or a failure variant

Auth API

Method	Path	Description
POST	/auth/login/email-password	Login with email/password, sets session cookie
POST	/auth/logout	Clears session cookie, deletes session from DB
GET	/auth/session	Returns current session (or None if not authenticated)

Cookie Constants

Constant	Value
SESSION_COOKIE_NAME	session_token
Cookie attributes	Path=/; HttpOnly; Secure

Email (bases/email)

SMTP email delivery via the Resend API.

pub async fn send_email(
    to_addresses: Vec<String>,
    subject: String,
    text_body: String,
    html_body: String,
) -> Result<(), AppError>

Loads ResendCoreConf (API key) and EmailAddressesCoreConf (domain, admin user) from core_conf.

Error Handling (bases/error)

A unified error type with automatic conversions:

#[derive(Debug, Error)]
pub enum AppError {
    Database(#[from] DbErr),       // SeaORM errors
    Io(#[from] std::io::Error),
    Http(#[from] reqwest::Error),
    NotFound(String),
    InvalidInput(String),
    Internal(String),
}

All service functions return Result<T, AppError>. The #[from] attributes enable ? operator on SeaORM, IO, and HTTP errors.

Background Jobs (bases/job)

#[async_trait]
pub trait JobTrait: Send + Sync {
    fn spec(&self) -> String;      // Cron expression
    async fn f(&self) -> ();       // Job execution
}

Implementors define a cron schedule and async work function. Concrete jobs live in feature modules (e.g., daily report scheduling).

Module Structure

src/bases/
├── error.rs      # AppError enum
├── conf/         # CoreConf trait + get_core_conf service
├── db/           # db_client() — SeaORM connection
├── auth/         # Session/AuthState extractors, login/logout API
├── email/        # send_email via Resend API
├── client/       # Dioxus app client entry point
└── job/          # JobTrait for scheduled background work

Related Modules

• Agent — uses OpenAICoreConf, GeminiCoreConf for provider settings
• Twilio — uses TwilioCoreConf for credentials
• OpenAI — uses OpenAICoreConf for API key
• Report — uses send_email for delivery