Functional Specification

This functional specification explains how Kaya currently works. It is an index into focused documentation pages rather than one large document.

Application overview

Kaya is a self-hosted infrastructure management application for homelabs, small IT environments and technical administrators.

It combines:

• Inventory tracking
• Remote access
• Runbooks
• Licence management
• IP/VLAN tracking
• DNS visibility
• Domain tracking
• Network monitoring
• Compute host monitoring
• Backup coordination
• Audit logging
• Site administration

Core concepts

• Users and roles
• Infrastructure records
• Operational modules
• Documentation/runbooks
• Settings
• Auditability
• Demo mode

See Overview and Architecture.

High level architecture

Kaya is a FastAPI/Jinja/SQLAlchemy application with local static assets, SQLite by default, Docker Compose deployment and Node helper services for remote access.

See Architecture.

Request flow

sequenceDiagram
  participant Browser
  participant FastAPI
  participant Session as Signed session cookie
  participant DB as SQLite
  participant Template as Jinja template

  Browser->>FastAPI: HTTP request
  FastAPI->>Session: Read signed session
  FastAPI->>DB: Load user/settings/data
  FastAPI->>FastAPI: Check permissions and CSRF where needed
  FastAPI->>Template: Render page
  Template-->>Browser: HTML response

Authentication, authorisation and sessions

See Security.

Database overview

See Database.

Configuration

Configuration comes from environment variables, generated runtime secrets and database-backed settings.

See Architecture and Site Administration.

Services and background tasks

Shared service modules handle audit logging, settings, custom fields, managed lists, email, import/export, provider integrations and background polling.

Background tasks include:

• Network monitor loop
• Domain polling loop
• Compute monitor loop
• Remote helper process management
• Guacamole bridge management

Module architecture

Each user-facing area has a module page:

• Dashboard
• Runbook Manager
• Remote Manager
• Networking
• DNS Manager
• Docker / Compute Manager
• Backup Manager
• Asset and Rack Management
• Licence Manager
• Site Administration
• Data Management

External integrations

See API & Integrations.

Deployment

See Deployment.

Security model

See Security.

Current limitations and technical debt

Current known limitations include:

• SQLite-first design.
• No formal Alembic migration system.
• Limited automated tests.
• Import/export only supports licences and IP addresses.
• RBAC is coarse-grained.
• No object-level permissions.
• Background workers run inside the web process.
• No queue system for backup jobs beyond database state.
• No antivirus/content scanning for uploads.
• No full REST API for most modules.
• Manual migration logic is duplicated across runtime startup and scripts/migrate_sqlite.py.
• RemoteManagerSetting stores many unrelated site-wide settings.