kayframework 0.1.1

Minimal FastAPI auth framework skeleton

KAYFRAMEWORK — Minimal FastAPI Framework

KAYFRAMEWORK is a minimal framework built on FastAPI. It provides a tiny core, a module system, and a CLI to scaffold modules. Everything else is intentionally left to the user.

---

1) Goal

• Minimal framework with a module system
• Small, readable core
• Users decide which features to add

---

2) Project Structure

app/
  api/              # Router and error handlers
  auth/             # Auth module (routes, schema, service, models)
  core/             # Config, security, dependencies
  db/               # DB session and base
  modules/          # Optional modules (loaded via MODULES)
  templates/        # Jinja2 templates
  utils/            # Helpers
  main.py           # App entry

kayframework/
  cli.py            # CLI entry

.env.example        # Environment sample
pyproject.toml      # Project + lint/format/type config

---

3) Setup

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

---

4) Environment (.env)

Use .env.example as a base to create .env.

Important vars

• SECRET_KEY: Must be long and random
• ENV: local or prod
• COOKIE_SECURE: false for local, true for production
• DATABASE_URL: SQLite or Postgres
• MODULES: comma-separated module list (example: blog,admin)

Example

SECRET_KEY=CHANGE_ME_USE_A_LONG_RANDOM_VALUE
ENV=local
LOG_LEVEL=INFO
DATABASE_URL=sqlite:///users.db
COOKIE_SECURE=false
MODULES=

---

5) Run

uvicorn app.main:app --reload

• Home: GET /
• Swagger: GET /docs

---

6) Module System

Modules live under app/modules/<name>/ and must expose router in routes.py.

Enable modules via .env:

MODULES=blog,admin

Routes will be mounted at:

/modules/blog
/modules/admin

---

7) CLI

Create a module scaffold:

kay new module blog

This generates:

app/modules/blog/
  __init__.py
  routes.py
  schema.py
  service.py
  models.py

Create a new project:

kay new app myproject

Run the app:

kay run

Run tests:

kay test

Lint:

kay lint

Format:

kay format

Type check:

kay typecheck

Version:

kay version

Build:

kay build

Clean:

kay clean

Init:

kay init

Doctor:

kay doctor

Help:

kay help

---

8) Tests

pytest

Current tests:

• Register + Login + Me flow

---

9) Lint / Format / Type

ruff check .
black --check .
mypy app

---

10) CI (GitHub Actions)

.github/workflows/ci.yml runs:

• ruff (lint)
• black --check (format)
• mypy (type)
• pytest (tests)

---

11) Install (Package)

Local editable install:

pip install -e .

With dev tools:

pip install -e ".[dev]"

---

12) Security Notes

• Replace SECRET_KEY before any real deployment.
• For ENV=prod, COOKIE_SECURE=true should be used.
• HTTPS is expected for production.

---

13) License

See LICENSE.