Orionis Application Skeleton

Write Python. Build the whole application.

Documentation • API reference • Website

This is the full application skeleton from the repository's master branch. It provides server-rendered authentication and administration pages, an API example, and route extension points for console commands, WebSockets, and MCP. The framework implementation is installed as the orionis dependency.

The application layout follows the framework repository's app/, bootstrap/, config/, database/, resources/, routes/, and public assets. All 17 application configuration modules are included. Framework library sources, its internal test suite, and API documentation build tools remain in the framework repository rather than the generated application.

Each variant is distributed as a branch of this repository:

Use Python 3.14+, uv, and Orionis 1.5 or later within 1.x. pyproject.toml declares the supported framework range. The initial uv sync resolves dependencies and creates a local uv.lock; that generated file is not included in this template.

Run commands from this application's root. For a new checkout, copy .env.example to .env if .env does not already exist. Use cp .env.example .env on POSIX shells or Copy-Item .env.example .env in PowerShell. Keep an existing application's environment values and key.

uv sync
uv run orionis key:generate

key:generate stores a new APP_KEY in .env and preserves an existing key unless explicitly forced. The example sets APP_URL to http://127.0.0.1:8000, matching the development server. Adjust it to the application's base URL and review the selected services in config/. .env.reference documents additional configuration variables.

The default SQL connection is SQLite at database/database.sqlite. Configure a different connection in .env and config/database.py before preparing its tables. Create the application's users table, then prepare the framework's authentication and authorization tables:

uv run orionis migrate
uv run orionis auth:migrate

auth:migrate creates permissions, roles, model_has_permissions, model_has_roles, role_has_permissions, personal access tokens, and password-reset storage. Run it before logging in, using recovery links, or running the optional seeder. These framework tables do not add entries to application migration history.

With .env.example, sessions and cache use file, queues use sync, and the scheduler defaults to memory. Sessions persist in storage/framework/sessions. Mail uses the file transport with an example sender, saving messages in storage/mail for local inspection; configure SMTP and a real sender to deliver email. If you choose database sessions or another SQL-backed service, prepare that service with its command below before starting requests or workers.

An optional demonstration seeder creates the admin role, the full_access permission, and an account with a fixed example password. Review and customize database/seeders/s0000000001_create_admin_authorization.py before running uv run orionis seed; the bundled account is intended for local development, not production provisioning. Seeding is not required to run the welcome page or health endpoints.

uv run orionis serve
uv run orionis test
uv run ruff check .

serve starts the development server; stop it before running other foreground commands in the same terminal. Inspect registered routes with uv run orionis route:list and available commands with uv run orionis list. The bundled reactor script remains an alternative, for example uv run python -B reactor test.

• bootstrap/app.py: application construction, route registration, service providers, lifecycle callbacks, middleware, and scheduler.
• routes/web.py: welcome page, authentication, profile, and administration routes.
• routes/api.py: the example GET /api/health endpoint.
• routes/ai.py, routes/console.py, and routes/websocket.py: extension points for the other runtime contexts.
• app/http/controllers/ and app/http/schemas/: application actions and validated inputs.
• app/console/listeners/, app/http/schemas/rules/, and app/jobs/: console listeners, validation rules, and queued jobs.
• app/contracts/, app/facades/, app/notifications/, and app/services/: extension points using the framework's standard directory names.
• app/mcp/ and app/realtime/: standard server/tool/resource/prompt and socket/hub directories, ready for registrations in their route files.
• resources/views/ and resources/lang/: server-rendered views and translations.
• storage/app/public/: public assets supplied with this template.
• database/: application migrations, versioned business schemas, factories, and seeders.
• tests/: application tests discovered by orionis test.

After setup, open / for the welcome page, /api/health for the example JSON response, or /up for the built-in health endpoint. Authentication pages require the application tables. The administration placeholders require the full_access permission, granted to the demo admin role by the optional seeder; ordinary accounts can use their dashboard and profile without it.

Orionis 1.5 owns authorization, personal access token, and password-reset schemas. The project therefore keeps only m0000000005_create_users_table.py and users_v1.py, alongside the user factory and optional demonstration seeder. It does not duplicate framework storage schemas or migrations. auth:migrate is required for the included authentication and administration flows; prepare other services only when you select their SQL-backed drivers:

These commands create missing tables from the framework definitions and preserve existing records. They do not execute application migrations, change incompatible schemas, or write migration history. They accept no --database option; select their connections in configuration. Scheduler storage uses its native table name directly; the other services honor the SQL connection prefix. See the storage preparation guide.

When updating an existing application, keep its applied migrations, their schemas, and migration history so rollback can still resolve them. The removed duplicate templates are not a request to delete existing project history or data. The user migration retains its original m0000000005 number.

Class methods use camelCase, _camelCase, or __camelCase; functions outside classes use snake_case. Python protocol methods retain their required names, such as __init__. Document Python APIs with NumPy-style docstrings.

Schema validation remains strict outside the scope of an explicit Coerce() marker. Coercion runs before type, constraint, and rule checks; Empty() and NoEmpty() are complementary empty-value rules. See schema declarations and empty-value rules when defining application inputs. Query builders also support toSql() for SQL inspection without executing a query.

• Framework source
• Skeleton variants
• Documentation
• CLI installer
• Discussions
• Support development

Created and maintained by Raul Mauricio Uñate Castro. Released under the MIT license.