Simezu Documentation

1. Overview

Simezu is a central identity, ownership, access, and payment context layer for multi-application ecosystems. It provides a single source of truth for users, groups, permissions, sessions, and payment profiles across connected applications.

What Problems Simezu Solves

Most authentication systems are designed for single applications. Real systems aren't. Users move between apps. Groups own resources. Permissions need to stay consistent. Sessions shouldn't break at every boundary. Simezu exists to solve this at the core—by acting as a shared identity and ownership layer, not just a login service.

Intended Usage and Audience

Simezu is designed for organizations building multiple connected applications that need shared identity across applications, consistent authorization decisions, centralized ownership and payment context, and cross-application session management.

This documentation is for developers evaluating Simezu conceptually, contributors, and technical readers who want to understand the architecture and model.

System Boundaries

Simezu provides:

• Identity management and authentication
• Authorization decisions and permission enforcement
• Session management across applications
• Payment profile management (not payment processing)
• Ownership and context tracking

Simezu does not provide application business logic, user interfaces, payment processing or execution, application-specific data storage, or stable external API contracts.

2. Core Concepts

Users

A user is a single identity that exists across all connected applications. Each user has a unique identifier, authentication credentials, profile information, and membership in zero or more groups. Users can own resources and have permissions granted directly or through group membership.

Groups

Groups represent collections of users with shared ownership, permissions, or context. Groups can own resources, receive payments, and have permissions that apply to all members. Groups are scoped to specific applications but can be referenced across the ecosystem.

Roles

Roles are named collections of permissions. Roles can be assigned to users or groups within an application context. A role defines what actions are allowed, not who can perform them. Role assignments determine effective permissions.

Permissions

Permissions are fine-grained access controls that define what actions can be performed on what resources. Permissions are evaluated centrally by Simezu but enforced by consuming applications. Permissions can be granted directly to users or inherited through group membership and roles.

Applications

An application is a connected system that consumes Simezu's identity, authorization, and context services. Each application has its own namespace for groups, roles, and permissions, while sharing the same user identity space. Applications are responsible for enforcing authorization decisions made by Simezu.

Sessions

A session represents an authenticated user's active state across the ecosystem. Sessions are managed centrally by Simezu and can be shared across multiple applications. Sessions carry identity, permissions, and context information that applications use to make authorization decisions.

Ownership

Ownership determines who has control over resources and actions. Resources can be owned by users or groups. Ownership affects authorization decisions—owners typically have elevated permissions on their resources. Ownership is tracked as part of the context that Simezu provides to applications.

Context

Context is the complete set of information about a user's current state: identity, group memberships, permissions, ownership relationships, and application-specific data. Context is assembled by Simezu and provided to applications to enable consistent authorization decisions across the ecosystem.

3. Identity Model

Single Identity Across Applications

Simezu maintains a single identity for each user across all connected applications. When a user authenticates, they authenticate once to Simezu, not to individual applications. This identity is consistent and persistent across the entire ecosystem.

Centralized Login State

Authentication happens at the Simezu layer. Applications do not maintain separate authentication systems. When a user logs in, Simezu establishes a session that can be used by any connected application. Applications receive identity information from Simezu, not from their own authentication mechanisms.

User Lifecycle

Users are created in Simezu's central identity store. Once created, a user exists across all applications. User profiles can include application-specific metadata, but core identity attributes are shared. Users can be deactivated, which affects their access across all applications, or deleted, which removes them from the system entirely.

Group Membership and Scope

Groups are created within application contexts but can be referenced ecosystem-wide. A user can be a member of multiple groups, potentially across different applications. Group membership affects permissions and ownership context. Groups can have owners, who are typically users with administrative privileges over the group.

4. Authorization Model

Permission-Based Access Control

Simezu uses a permission-based authorization model. Permissions are granular statements about what actions can be performed on what resources. Permissions are evaluated centrally by Simezu, but enforcement happens in consuming applications.

Roles and Group-Scoped Permissions

Roles provide a way to bundle permissions together. A role can be assigned to a user or group within an application context. When assigned to a group, all members of that group inherit the role's permissions. Permissions can also be granted directly to users or groups without using roles.

Centralized Decision-Making

Simezu makes authorization decisions centrally. When an application needs to know if a user can perform an action, it queries Simezu with the user's identity, the requested action, and the resource context. Simezu evaluates all relevant permissions—direct grants, role-based permissions, and group memberships—and returns an authorization decision.

Why Permissions Live Centrally

Centralizing permissions ensures consistency across applications. If a user's permissions change, that change is reflected immediately across all applications. There is no need for synchronization jobs or eventual consistency mechanisms. Applications always receive the current, authoritative permission state.

5. Application Integration (Conceptual)

What Integration Means

An application integrates with Simezu by delegating identity, authorization, and context management to Simezu. The application does not maintain its own user database, authentication system, or permission store. Instead, it queries Simezu for identity information and authorization decisions.

Responsibilities of Consuming Applications

Applications are responsible for:

• Enforcing authorization decisions made by Simezu
• Storing and managing application-specific data
• Implementing business logic
• Providing user interfaces
• Handling application-specific workflows

Applications are not responsible for authenticating users, making authorization decisions, managing user credentials, or maintaining permission state.

What Applications Receive

Applications receive from Simezu:

• User identity and profile information
• Current group memberships
• Effective permissions for the current context
• Ownership relationships
• Session state and validity

What Applications Must Handle

Applications must handle storing application-specific data, implementing business logic, rendering user interfaces, processing payments (Simezu provides payment profiles, not payment execution), and application-specific workflows and state management.

6. Ownership & Context

Users vs Groups as Owners

Resources can be owned by either users or groups. User ownership is straightforward—a single user has control. Group ownership means the group collectively owns the resource, and group members may have permissions based on their membership. Ownership affects authorization decisions and payment routing.

Ownership of Resources and Actions

Ownership is tracked as part of the context that Simezu maintains. When an application queries for authorization, it provides resource context, including ownership information. Simezu evaluates permissions in the context of ownership—owners typically have elevated permissions, and group members may have permissions based on group ownership.

How Ownership Affects Authorization

Ownership is a factor in authorization decisions. A user who owns a resource may have different permissions than a user who does not. Group ownership means all group members may have permissions based on the group's ownership. Ownership relationships are part of the context that applications provide when querying for authorization.

Why Context is Critical

In multi-application systems, context is essential for consistent authorization. A user's permissions may vary depending on which application they're using, which group they're acting on behalf of, or which resource they're accessing. Simezu assembles this context and uses it to make consistent authorization decisions across all applications.

7. Payments (High-Level)

Why Payments are Part of Simezu's Model

Payments are a form of ownership and context. Users and groups need payment profiles to receive payments, and applications need to know which payment profile to use in different contexts. By managing payment profiles centrally, Simezu ensures consistent payment routing across applications and maintains the relationship between identity and payment capability.

Payment Profiles

Payment profiles are attached to users or groups. A user can have a personal payment profile, and a group can have a group payment profile. Payment profiles contain information about payment methods (Stripe accounts, PayPal emails, SEPA bank details) but do not contain payment processing logic.

Per-Application Payment Context

Applications can query Simezu for payment profiles in specific contexts. For example, if a group owns a resource and receives payment for that resource, the application can query Simezu for the group's payment profile. Simezu returns the appropriate profile based on ownership and context.

Supported Providers

Simezu supports payment profile management for Stripe (connected accounts), PayPal (email addresses), SEPA (bank account details), and Wero (planned). These are payment profile providers, not payment processors. Simezu stores payment account information and provides it to applications, but does not execute payments.

Simezu Does Not Process Payments

Simezu explicitly does not process payments. It manages payment profiles—information about where payments should be sent—but does not execute payment transactions, handle payment flows, or interact with payment processors beyond storing account information. Applications are responsible for using payment profiles to execute actual payment transactions.

Boundaries of Responsibility

Simezu is responsible for storing payment profile information, associating payment profiles with users and groups, and providing payment profiles to applications in context.

Simezu is not responsible for executing payment transactions, handling payment flows or user interactions, interacting with payment processors beyond account storage, managing payment disputes or refunds, or processing payment webhooks or callbacks.

8. Sessions & State

Central Session Handling

Simezu manages sessions centrally. When a user authenticates, Simezu creates a session that represents their authenticated state. This session is valid across all connected applications and contains identity, permission, and context information.

Cross-Application Session Sharing

Sessions are shared across applications. When a user logs into one application, they are effectively logged into all applications that trust Simezu's session state. Applications can query Simezu to validate sessions and retrieve current user context without requiring separate authentication.

High-Level Token Concepts

Simezu uses tokens to represent sessions and carry identity information. These tokens are issued by Simezu and validated by applications. Tokens contain identity and permission information that applications use to make authorization decisions. Token formats and validation mechanisms are internal implementation details.

Session Lifecycle and Invalidation

Sessions are created on authentication and can be invalidated explicitly (logout) or automatically (expiration, security events). When a session is invalidated, it becomes invalid across all applications immediately. Applications are responsible for respecting session validity and re-authenticating when sessions expire.

9. Security Principles

Authentication Security

Simezu implements secure authentication practices including strong password hashing, secure session management, and protection against common authentication attacks. Authentication credentials are stored securely and never exposed to applications. Applications receive only identity information, not credentials.

Authorization Enforcement

Authorization decisions are made centrally by Simezu, but enforcement happens in applications. Simezu provides clear authorization decisions, and applications are responsible for respecting these decisions. This separation ensures that authorization logic is centralized while allowing applications to implement enforcement in ways that fit their architecture.

Rate Limiting and Abuse Prevention

Simezu implements rate limiting and abuse prevention mechanisms to protect against brute force attacks, credential stuffing, and other abuse patterns. These mechanisms operate at the authentication and API layers to prevent abuse before it reaches applications.

Auditability

Simezu maintains audit logs of authentication events, authorization decisions, and administrative actions. These logs provide a record of who did what and when, enabling security investigations and compliance requirements. Applications can also maintain their own audit logs for application-specific events.

10. Scalability & Architecture

Multi-App Scaling Philosophy

Simezu is designed to scale with the number of connected applications and users. The architecture assumes that adding new applications does not require changes to existing applications or to Simezu's core systems. Each application integration is independent.

Stateless Integration Principles

Applications integrate with Simezu in a stateless manner. Applications do not maintain persistent connections or server-side state with Simezu. Instead, they make stateless requests for identity and authorization information as needed. This allows applications to scale independently and simplifies deployment.

Horizontal Scaling

Simezu is designed to scale horizontally. The system can handle increased load by adding more instances rather than requiring more powerful hardware. This design assumes that session state and authorization decisions can be made without requiring coordination between instances for most operations.

Operational Assumptions

Simezu assumes that applications can make network requests to Simezu, network latency between applications and Simezu is acceptable for authorization queries, applications handle Simezu unavailability gracefully, and applications implement appropriate caching of authorization decisions when needed.

11. Extensibility

Modular Design Philosophy

Simezu is designed with modularity in mind. New capabilities can be added without disrupting existing functionality. The permission model, ownership model, and payment profile system are all designed to evolve over time without breaking existing integrations.

Adding New Applications

New applications can be added to the ecosystem without affecting existing applications. Each application has its own namespace for groups, roles, and permissions, so adding a new application does not create conflicts with existing applications. User identity is shared, but application-specific data is isolated.

Evolving the Model

The permission model, ownership model, and other core concepts can evolve over time. Simezu is designed to support new permission types, new ownership patterns, and new context information without requiring changes to all consuming applications. Applications can adopt new capabilities as needed.

12. Non-Goals & Limitations

What Simezu Intentionally Does Not Provide

Simezu does not provide business logic or application workflows, user interfaces or frontend components, payment processing or execution, application-specific data storage, content management or media handling, communication or messaging systems, analytics or reporting beyond audit logs, or stable external API contracts for third-party integration.

Explicit Exclusions

Simezu excludes payment execution (Simezu manages payment profiles but does not process payments), UI components (applications must build their own user interfaces), business logic (applications implement their own workflows and rules), data storage (applications store their own application-specific data), and external APIs (Simezu does not provide stable external API contracts).

Misuse Patterns to Avoid

Do not use Simezu for storing application-specific business data, implementing application workflows, processing payments directly, building user-facing features that should be in applications, creating dependencies on internal implementation details, or assuming API stability or external support guarantees.

13. Glossary