Application Lifecycle

Application Lifecycle

This document describes how an HTTP request is processed by AutoDoc.

Startup Sequence

When the application starts, the following sequence occurs:

Passenger (cPanel) / Uvicorn (local)
    │
    ▼
passenger_wsgi.py  /  uvicorn autodoc.app:app
    │
    ▼
app.py (imports create_app)
    │
    ▼
create_app() factory
    │
    ├── Creates FastAPI instance
    ├── Registers routes (health, auth, documents, playground, static UI)
    ├── Auto-migrates the database schema (create_tables + sync_missing_columns)
    ├── Registers exception handlers + middleware
    ├── Initializes providers (AI, etc.)
    │
    ▼
FastAPI Application ready

Startup Flow

1. Entry Point

cPanel (Phusion Passenger): The entry point is passenger_wsgi.py at the project root. It: - Adds src to Python's import path - Imports the application from src/autodoc/app.py - Wraps the ASGI app using a2wsgi to produce a WSGI callable named application

Local development:

uvicorn autodoc.app:app --reload --host 0.0.0.0 --port 8000

The project-generator feature this project was spawned from (create-project.sh / /playground/project) is intentionally disabled here (ENABLE_PROJECT_GENERATOR unset) — AutoDoc is a leaf application, not a template for spawning further projects.

2. Application Entry Point

src/autodoc/app.py remains minimal — its only job is to import and expose the factory:

from autodoc.core.application import create_app

app = create_app()

3. Application Factory

create_app() in core/application.py is responsible for:

• Creating the FastAPI instance with title, version, description
• Mounting /static and registering routes: / (UI), /health, /auth/*, /documents/*, /playground/*, /guide/*
• Initializing exception handlers + middleware
• Initializing providers (AI, etc.)
• Auto-migrating the database schema (create_tables() + sync_missing_columns() — see Document Processing note on schema evolution, and PROJECT_STATUS.md for the NOT-NULL-column limitation)

GET / serves src/autodoc/static/index.html (Login/Register/Logout + Documents + admin Members UI) directly. If that file is ever missing, it falls back to a small JSON status payload instead:

{
    "framework": "IndiaPRIDE AutoDoc",
    "version": "0.1.0",
    "status": "running"
}

4. Configuration Initialization

During create_app(), the configuration system initializes:

1. Pydantic Settings loads .env file (case-insensitive, extra="ignore")
2. FrameworkSettings singleton is created, holding:
3. ApplicationConfiguration — app name, version, host, port, debug, environment
4. DatabaseSettings — DATABASE_URL, echo (nested inside ApplicationConfiguration)
5. LoggingSettings — log level (nested inside ApplicationConfiguration)
6. Environment enum determines runtime behavior (DEVELOPMENT, TESTING, STAGING, PRODUCTION)

5. Database Initialization

When the database provider is included:

1. get_engine() reads DATABASE_URL from config (falls back to sqlite:///./indiapride.db if unset — the fallback filename predates this project's rename from the framework template and is harmless since production always sets DATABASE_URL explicitly, to the MySQL indiapri_autodoc database)
2. SQLite connections get check_same_thread=False automatically
3. Base = DeclarativeBase() is the single base class for all ORM models
4. create_tables() creates all tables from registered models (dev/testing only)
5. get_db provides a FastAPI dependency that yields a session with auto-commit/rollback

6. Request Processing

HTTP Request
    │
    ▼
Passenger / Uvicorn
    │
    ▼
FastAPI (routing, validation, serialization)
    │
    ▼
Route Handler
    │
    ├── Depends(get_db) → SQLAlchemy session
    │
    ▼
Response

Already implemented

• Authentication/Authorization — JWT-based login/register/bootstrap, plus admin-only member management with admin/manager/user roles enforced via require_role. See Member Management.
• Document processing — upload, placeholder detection, values input, page-fit generation via LibreOffice. See Document Processing.
• AI Providers — AIProvider base + OpenAI implementation, auto-wired via create_app() (inherited from the framework template; not currently used by any AutoDoc feature).
• Deployment identity check — /playground/identity reports the on-disk folder/package/app name actually serving the request, to catch cPanel misconfiguration.
• Docs viewer — /guide renders this project's own markdown documentation as HTML.

Future Expansion

Not yet started (see PROJECT_STATUS.md for the current list):

• Formal test suite
• Cleanup of the inherited-but-unused project-generator files
• Monitoring LibreOffice resource usage under real concurrent load

Design Philosophy

The application entry point (app.py) and factory (create_app()) should remain stable. Business logic belongs inside autodoc modules rather than startup files. This keeps deployment simple while allowing the application to grow without changing deployment configuration.