I have been fascinated by Japanese culture for a very long time. One aspect that has always caught my attention is the longevity and overall health of Japanese people.

An interesting element of Japanese culture is that people spend a lot of time sitting on the floor. Most of you have probably seen scenes in Japanese movies where people sit on the floor around a low table.

This made me wonder whether sitting on the floor could be one of the factors contributing to their health and longevity, and whether I could apply this habit to my own life.

Every time you sit down on the floor and get back up, your body has to perform a physical movement. In a way, it is similar to doing a squat each time, and squats are very beneficial for the body. In addition, sitting in a meditation-like position encourages us to maintain better posture.

Since I had already been practicing meditation for a long time and owned a meditation cushion, I decided to run an experiment: I replaced the office chair I used for work with my meditation cushion.

I modified my desk so that its height would be suitable for working while sitting on the floor, and I began the experiment.

The First Month

The first month was much more difficult than I expected. After the first few days, I was already close to giving up. My knees and back hurt, and despite my experience with meditation, I did not feel comfortable sitting on the floor for such a long time.

It quickly became clear that sitting on the floor for eight hours a day was very different from meditating for thirty minutes.

Despite the initial difficulties, I decided to continue the experiment and give my body enough time to adapt.

After the first month, the pain in my knees and back disappeared, and I started to feel much more comfortable. I also noticed a slight improvement in my posture.

Two Years Later, I Still Work on the Floor

It has now been two years since I started this experiment, and I have no intention of going back to sitting in an office chair. I feel much better than I did before, my posture has improved significantly, and I can no longer imagine spending many hours sitting in a comfortable office chair—which, ironically, no longer feels comfortable to me at all.

I have also discovered that sitting on the floor allows us to use many different positions, which can also have a positive effect on the body. Spending the entire day in a single position is very unhealthy.

Yoga can be helpful here. Many asanas can be adapted to sitting and working at a computer, allowing us to regularly change the position in which we work.

What do you think about this kind of workspace? Would you consider replacing your chair with a floor setup? Or maybe you have your own unusual way of working at a computer that makes you feel more comfortable or helps you stay active?

Originally published on CoderLegion.

Until you implement it for the fifth time.

Registration, login, sessions, email verification, password resets, password changes, account deletion, roles, permissions — none of these features are particularly unusual. But almost every application needs some combination of them, and the implementation often ends up tightly coupled to whatever framework, ORM, or infrastructure the project happened to use at the time.

That was the problem that led me to build UserHarbor.

UserHarbor is a framework-agnostic Python library for user account management. The goal is not to build another web framework or a complete identity platform. Instead, it provides a small domain-level API for common account operations while leaving HTTP, databases and email delivery to separate integrations.

Since I first wrote about the project, the interesting part has increasingly become not just the authentication API itself, but the boundary between the core and its integrations.

This article expands on my original introduction to UserHarbor, focusing on how the architecture evolved as the project grew.

The problem I wanted to solve

Imagine building two applications.

One uses:

• FastAPI
• SQLAlchemy
• PostgreSQL
• SMTP

Another uses:

• Flask
• MongoDB
• an external email API

The user-management rules are mostly the same.

A password still needs to be validated and hashed. A verification token still needs to expire. Password reset tokens still need to be protected. Sessions need to be created and invalidated. Roles and permissions need to be checked.

But in many libraries these rules are mixed together with database models, HTTP handlers or framework-specific abstractions.

I wanted the opposite.

The core should know what should happen, but not necessarily how the application stores or transports the data.

That leads to an architecture that looks roughly like this:

Application / Framework
        │
        ▼
    UserHarbor
        │
        ├── UserStore
        │       └── database / ORM / custom backend
        │
        └── EmailSender
                └── SMTP / API / custom provider

The core owns things such as registration, validation, password hashing, token generation, token hashing, session handling and authorization rules.

The adapters own infrastructure.

A small domain-level API

UserHarbor currently handles the common account lifecycle:

• user registration
• email verification
• login
• sessions
• logout from one or all sessions
• password change
• password reset
• account deletion
• roles and permissions

It deliberately does not expose HTTP endpoints itself.

That means code using the core can look like this:

user = harbor.register(
    username="jane",
    email="*Emails are not allowed*",
    password="StrongPassword123!",
)

harbor.verify_email(verification_token)

session_token = harbor.login(
    username="jane",
    password="StrongPassword123!",
)

current_user = harbor.get_current_user(session_token)

The same UserHarbor instance can be used from FastAPI, Flask, Django, a CLI application or something that does not expose HTTP at all.

Authorization follows the same idea:

harbor.roles.create("admin")
harbor.permissions.create("users.delete")

harbor.roles.grant_permission(
    "admin",
    "users.delete",
)

harbor.grant_role("jane", "admin")

if harbor.has_permission(session_token, "users.delete"):
    delete_user()

Or, if access should be enforced:

user = harbor.require_permission(
    session_token,
    "users.delete",
)

UserHarbor implements simple role-based access control, but leaves application-specific authorization policy outside the core. It intentionally does not try to become a general policy engine.

Framework-agnostic does not mean framework-unfriendly

One thing I wanted to avoid was making framework independence come at the cost of developer experience.

For example, there is an official userharbor-fastapi integration.

Instead of manually writing authentication routes and dependencies, a FastAPI application can configure UserHarbor and attach the adapter:

from fastapi import FastAPI
from userharbor import UserHarbor
from userharbor_fastapi import UserHarborFastAPI

harbor = UserHarbor(
    secret_key="your-secret-key",
    store=store,
    email_sender=email_sender,
)

auth = UserHarborFastAPI(harbor)

app = FastAPI()
app.include_router(
    auth.router,
    prefix="/auth",
    tags=["auth"],
)

The adapter provides the framework-specific layer: routers, request schemas, bearer authentication dependencies, error mapping and helpers for requiring roles or permissions.

The important part is that FastAPI still does not leak into the UserHarbor core.

You can replace the web framework without replacing the account-management logic.

The harder problem: what does it mean to implement UserStore?

Originally, separating persistence behind a UserStore interface seemed like the obvious solution.

Define an interface, implement the methods, and now SQLAlchemy, MongoDB, Redis or anything else can provide storage.

But there is a subtle problem.

Matching method signatures does not mean two storage implementations behave the same way.

Consider a password reset token.

Should creating a new token remove an older token?

What happens when a user is deleted?

Should their sessions disappear automatically?

What should happen if a transaction fails halfway through a password change?

Should deleting something that no longer exists raise an error?

These behaviors are part of the storage contract even though Python’s type system cannot express them.

This became one of the most important changes in UserHarbor 0.7.0.

Turning the adapter contract into executable tests

UserHarbor now ships a reusable contract test suite for UserStore implementations.

An adapter can import the complete suite:

# tests/test_user_store_contract.py

from userharbor.testing.user_store_contract import *

Then it only needs to provide a clean store:

import pytest


@pytest.fixture
def user_store():
    store = create_user_store()

    try:
        yield store
    finally:
        dispose_user_store(store)

The same tests can then run against SQLAlchemy, an in-memory implementation, or a completely different persistence backend.

Version 0.7.0 introduced 57 reusable contract tests covering users, password hashes, verification tokens, password reset tokens, sessions, roles, permissions, relationships and transaction behavior.

This changes the meaning of an adapter.

A compatible UserStore no longer just claims to implement an interface. It can demonstrate that it follows the behavioral semantics expected by the core.

For example, the contract specifies that:

• usernames and email addresses are unique
• user creation and the initial verification token are atomic
• a new verification token replaces the previous one
• a new password reset token replaces the previous one
• deleting a user removes their sessions and related tokens
• repeated relationship assignments are idempotent
• deleting roles and permissions removes their assignments
• successful transactions commit
• failed transactions roll back
• nested transactions participate in the outer transaction

These details are easy to overlook when implementing another backend, and they are exactly the type of differences that can produce authentication bugs which only appear much later.

For me, this was an important step in the architecture: the abstraction is now described not only by Python protocols and documentation, but also by executable behavior.

A template for building new storage adapters

To make that process easier, I also created userharbor-inmemory.

It is a minimal in-memory UserStore implementation that passes the complete storage contract.

It serves two purposes.

First, it is useful for tests and examples where a real database is unnecessary.

Second, the repository itself can be used as a template for creating new storage integrations. A developer can start with a working implementation and passing contract tests, replace the in-memory backend incrementally, and continuously verify that the new adapter still behaves correctly.

The idea is that creating something like a future database adapter should mostly become:

working UserStore template
        │
        ▼
replace persistence implementation
        │
        ▼
run shared contract tests
        │
        ▼
add backend-specific tests

instead of reverse-engineering the expected behavior from the core implementation.

Keeping security behavior inside the core

Another important architectural boundary is that storage adapters never receive raw tokens for persistence.

UserHarbor generates the raw verification, reset and session tokens, but hashes them before passing them to UserStore.

The raw token is given only to the part of the application that needs it — for example, to an email sender or to the user after login.

The database stores the hash.

The core also owns behavior such as token expiration and session validation.

Sensitive account-discovery flows are designed to return neutral responses where appropriate. For example, requesting a password reset for an unknown email address does not reveal whether that account exists.

There are also account lifecycle notifications for events such as:

• successful email verification
• password changes
• password resets
• account deletion

The EmailSender interface decides how those messages are delivered, but it does not decide when the operation is valid. That decision remains in the core.

SQLAlchemy without owning your application

The official SQLAlchemy adapter is useful out of the box, but one design requirement was that adopting UserHarbor should not force an application to adopt a completely separate user model.

By default, the adapter can manage its own user table.

But applications that already have a SQLAlchemy model can provide it instead:

store = SQLAlchemyUserStore(
    SessionLocal,
    user_model=AppUser,
)

Applications can also map their model to a richer public user object instead of being limited to UserHarbor’s minimal representation.

The documentation now also covers using the adapter with Alembic migrations rather than relying on metadata.create_all() at application startup.

That distinction matters because examples should be easy to run, but real applications need a sensible path toward managing schema changes properly.

Installation

The core can be installed on its own:

pip install userharbor

Or with selected official integrations:

pip install "userharbor[sqlalchemy,smtp,fastapi]"

For experimenting with the complete official stack:

pip install "userharbor[all]"

The main official integrations currently include SQLAlchemy storage, SMTP email delivery and FastAPI support.

What I deliberately do not want UserHarbor to become

Feature creep is an easy trap for this kind of project.

Once you have authentication, it is tempting to add OAuth. Then social login. Then MFA. Organizations. Teams. ACLs. Resource ownership. Admin panels. A policy language.

Eventually the “small authentication library” becomes an application framework.

That is specifically what I am trying to avoid.

The core should remain focused on common account-management primitives.

More specialized functionality can exist as integrations or separate libraries if there is demand for it, but it should not make the basic package more complicated for everyone else.

One of the design principles of UserHarbor is therefore deliberately boring:

stability is more important than feature count.

Once the public API stabilizes, I would rather spend development effort on security, reliability, compatibility and performance than continuously expand the scope of the core.

Current status

UserHarbor is currently at version 0.7.0.

The project is still young, and I do not consider the API stable or the library ready for production use yet.

At this stage, the project is as much about validating the architecture as adding functionality.

The areas I am particularly interested in getting feedback on are:

• the boundary between the core and integrations
• the UserStore contract
• the contract-testing approach
• the FastAPI integration
• custom storage backends
• the shape of the public API
• what should — and should not — belong in the core

There are plenty of good framework-specific authentication libraries in Python.

UserHarbor is exploring a slightly different question:

Can the account-management domain itself be reusable across frameworks and infrastructure, while integrations remain small, replaceable and independently testable?

So far, I think that boundary is turning out to be the most interesting part of the project.

Links

Documentation:
https://userharbor.github.io/userharbor/

Repository:
https://github.com/userharbor/userharbor

FastAPI integration:
https://github.com/userharbor/userharbor-fastapi

SQLAlchemy adapter:
https://github.com/userharbor/userharbor-sqlalchemy

SMTP adapter:
https://github.com/userharbor/userharbor-smtp

Originally published on CoderLegion.

• registration
• login
• sessions
• email verification
• password reset
• password change
• account deletion
• basic roles and permissions

None of that was especially hard.

But it was repetitive.

I had written similar code before, and I did not want to keep rebuilding the same user-management boilerplate in every new Python project.

So I started working on UserHarbor.

What is UserHarbor?

UserHarbor is a framework-agnostic Python library for user account management.

The idea is simple:

keep the core small, predictable, and independent from any specific web framework, database, ORM, or email provider.

The core handles the account-management logic. Integrations are handled by separate adapter packages.

So instead of building something only for FastAPI, Flask, Django, or one specific stack, I wanted a core that could be used in different kinds of Python applications.

For example:

• FastAPI apps
• Flask apps
• Django apps
• CLI tools
• internal tools
• custom Python services

Why not just use a framework-specific library?

There are already good tools for specific frameworks.

But I wanted something slightly different.

I did not want the user-management logic to be tightly coupled to:

• a web framework
• a database layer
• an email provider
• a specific request/response model

Instead, UserHarbor uses small interfaces for things like storage and email delivery.

The main interfaces are:

class UserStore:
    ...

class EmailSender:
    ...

The core does not care how users are stored or how emails are sent.

That part belongs to adapters.

Installation

Install only the core package if you want to provide your own UserStore and EmailSender implementations:

pip install userharbor

Install the core package with the official SQLAlchemy, SMTP, and FastAPI adapters:

pip install "userharbor[sqlalchemy,smtp,fastapi]"

Or install all official integrations at once:

pip install "userharbor[all]"

Official adapters

At the moment, there are a few official adapter packages:

• userharbor-sqlalchemy — SQLAlchemy storage
• userharbor-smtp — SMTP email sender
• userharbor-fastapi — FastAPI integration

This keeps the core small while still making the common setup easy to install and use.

Quick example

Here is a longer example using SQLAlchemy storage and SMTP email delivery:

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

from userharbor import UserHarbor
from userharbor_sqlalchemy import SQLAlchemyUserStore
from userharbor_smtp import SMTPEmailSender

engine = create_engine("sqlite:///users.db")
SessionLocal = sessionmaker(bind=engine)

store = SQLAlchemyUserStore(SessionLocal)
store.metadata.create_all(engine)

email_sender = SMTPEmailSender(
    host="smtp.example.com",
    port=587,
    username="smtp-user",
    password="smtp-password",
    from_email="noreply@example.com",
)

harbor = UserHarbor(
    secret_key="your-secret-key",
    store=store,
    email_sender=email_sender,
)

# Register a user
harbor.register(
    username="jane",
    email="jane@example.com",
    password="StrongPassword123!",
)

# Verify email address
harbor.verify_email("verification-token-from-email")

# Login
session_token = harbor.login(
    username="jane",
    password="StrongPassword123!",
)

# Verify session
if harbor.verify_session(session_token):
    print("User is logged in")

# Get current user
current_user = harbor.get_current_user(session_token)
print(current_user.username)

# Create roles and permissions
harbor.roles.create("admin")
harbor.permissions.create("users.delete")

harbor.roles.grant_permission("admin", "users.delete")
harbor.grant_role("jane", "admin")

# Check access
if harbor.has_permission(session_token, "users.delete"):
    print("User can delete users")

current_admin = harbor.require_role(session_token, "admin")
print(current_admin.username)

# Logout
harbor.logout(session_token)

# Change password
session_token = harbor.login(
    username="jane",
    password="StrongPassword123!",
)

harbor.change_password(
    old_password="StrongPassword123!",
    new_password="EvenStrongerPassword123!",
    session_token=session_token,
)

# Send password reset email
harbor.send_password_reset("jane@example.com")

# Reset password
harbor.reset_password(
    new_password="NewStrongPassword123!",
    reset_token="reset-token-from-email",
)

# Delete account
session_token = harbor.login(
    username="jane",
    password="NewStrongPassword123!",
)

harbor.delete_account(
    password="NewStrongPassword123!",
    session_token=session_token,
)

Full FastAPI example with official integrations

If you want to try the full setup with FastAPI, SQLAlchemy, and SMTP, install all official integrations:

pip install "userharbor[all]"

Then create a FastAPI application:

import os

from fastapi import FastAPI
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

from userharbor import UserHarbor
from userharbor_fastapi import UserHarborFastAPI
from userharbor_smtp import SMTPEmailSender
from userharbor_sqlalchemy import SQLAlchemyUserStore

engine = create_engine("sqlite:///users.db")
SessionLocal = sessionmaker(bind=engine)

store = SQLAlchemyUserStore(SessionLocal)
store.metadata.create_all(engine)

email_sender = SMTPEmailSender(
    host=os.getenv("HOST", "smtp.example.com"),
    port=int(os.getenv("PORT", 587)),
    username=os.getenv("USERNAME"),
    password=os.getenv("PASSWORD"),
    from_email=os.getenv("USERNAME", ""),
)

harbor = UserHarbor(
    secret_key="your-secret-key",
    store=store,
    email_sender=email_sender,
)

auth = UserHarborFastAPI(harbor)

app = FastAPI()

app.include_router(auth.router, prefix="/auth", tags=["auth"])

if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="0.0.0.0", port=8000)

Design principles

The project is built around a few constraints.

The core should stay small

UserHarbor is not meant to become a full identity platform.

The core focuses on basic account-management flows:

• registration
• login
• sessions
• email verification
• password reset
• password change
• account deletion
• simple role-based access control

Anything highly application-specific should stay outside the core.

Adapters should live outside the core

Database, ORM, email, and framework integrations should be separate packages.

That keeps the core independent and makes it easier for other people to build their own integrations.

For example, someone could build:

• userharbor-redis
• userharbor-mongodb
• userharbor-sendgrid
• userharbor-resend
• userharbor-django
• userharbor-flask

without changing the main package.

The API should be boring

I am trying to keep the public API explicit and predictable.

No hidden framework magic. No forced database model. No dependency on one specific way of building Python applications.

Current status

The project is still early.

The basic flows work, but I do not consider the API fully stable yet. It is not something I would call production-ready today.

Right now I am mostly looking for feedback around:

• the public API
• the adapter architecture
• the boundary between core and integrations
• the SQLAlchemy integration
• the FastAPI integration
• whether simple RBAC belongs in the core
• what a good developer experience for custom adapters should look like

Links

Documentation:
https://userharbor.github.io/userharbor/

Repository:
https://github.com/userharbor/userharbor

FastAPI integration:
https://github.com/userharbor/userharbor-fastapi

SQLAlchemy adapter:
https://github.com/userharbor/userharbor-sqlalchemy

SMTP adapter:
https://github.com/userharbor/userharbor-smtp

Feedback welcome

I would appreciate any feedback, especially from people who have built user-management flows multiple times in Python projects.

Does this adapter-based approach make sense?

Would you expect simple roles and permissions to be part of the core, or should they live in a separate package?

And if you were integrating this into your own project, what would you want the API to look like?

Update: I later wrote a deeper architectural follow-up about UserHarbor’s adapters and executable storage contract.

Originally published on DEV Community.

My projects include libraries, real-time APIs, database tools and automation for everyday development tasks. Whatever the area, I care about clear architecture, simple solutions and tools that solve a specific problem without unnecessary complexity.

In both work and life, I try to follow the principle: Simple is better than complex.

Selected projects

• UserHarbor — a framework-agnostic user management system for Python applications.
• SocketAPI — a lightweight real-time API framework using one multiplexed WebSocket connection with endpoint-like actions and subscriptions.
• SQLift — a deliberately small command-line migration tool for SQL databases.
• ORMagic — a simple and lightweight ORM for Python, built on top of Pydantic.
• autopy.fish and autoenv.fish — Fish plugins that automatically activate Python environments and load variables from .env files.

Find me online

• GitHub
• LinkedIn
• CoderLegion
• spaceshaman@tuta.io