Skip to main content

System Architecture

Functional overview of how Axvero is structured — intended for product stakeholders, administrators, and anyone trying to understand how the pieces fit together.

The Three Layers​

Axvero is organized around three distinct concerns: who people are, how they are organized, and what they work on.

A single user can simultaneously be an owner of their own organization, a staff member in a colleague's organization, and a client applicant in a bank — all with one account.

Organization Structure​

Each organization owns one or more workspaces (work contexts). Staff access is controlled through teams. Clients are assigned directly to the organization and can participate in applications across all org workspaces.

Key insight: Teams are org-level — not tied to a single workspace. Assigning a team to a new workspace instantly grants all its members access. Clients are also org-level — they are not scoped to any single workspace.

How Access Works​

A staff member's access to a workspace is determined by which team they belong to. Each team has a base role that applies to every workspace it is assigned to.

An individual role override can be set on a team member if one person needs a different permission than the team default — without creating a new team for them.

Role Hierarchy​

Roles form a strict hierarchy. Each role includes all permissions of the roles below it.

Invitation & Account Creation Flow​

Both staff and client accounts are pre-created immediately when invited. The office can assign them to applications and see them in rosters right away — the invited person completes onboarding at their own pace.

The invitation email contains an account-setup link (verify email + set password + update profile). It does not contain an org-join link — the user is already added to the org at invitation time. Activation into a team happens automatically once the scheduler detects that all required actions have been completed (runs every 2 minutes).

Pending invitations that are never accepted are cleaned up automatically:

  • Day 20 — reminder email sent
  • Day 30 — Keycloak account deleted and the Member / Client record is deleted

Org-to-Org Relationships​

Organizations can formally partner with other organizations as Agents (submit applications on behalf of clients) or Sub-contractors (provide operational services).

Partner org members are regular TeamMembers in a specific team within the target org — no special access model is needed.

Application Lifecycle​

Applications live in workspaces and move through a configurable workflow.

Document lifecycle:

Personal Workspace — Cross-Org Aggregation​

Every user has a personal workspace (/p/$userSlug/). Its applications view is a unified inbox across all organizations the user participates in.

Clicking any application opens it in its own workspace context — the URL becomes /o/$orgSlug/w/$workspaceSlug/applications/$id/. The personal view is for discovery; work happens in the workspace.

The frontend renders a different sidebar depending on the active workspace type and purpose.

Workspace Switcher​

The switcher at the top of the sidebar lists all workspaces. When a user has more than 3 org workspaces, a search input and filter tabs appear:

  • Staff — workspaces with workspacePurpose = STAFF or MIXED
  • Client — workspaces with workspacePurpose = CLIENT or MIXED
  • All — no filter

The switcher defaults to the Staff tab. Personal workspaces are always pinned below the scrollable list.

Staff Workspace Sidebar​

Two sections, always rendered in this order:

WORKSPACE — scoped to the active workspace (/o/orgSlug/w/workspaceSlug/):

  • Dashboard
  • Applications
  • Messages (with unread badge)
  • App Setup (collapsible: Documents, Templates, Permissions) — permission-gated (ManageApplicationSetup)

MANAGEMENT — scoped to the org (/o/orgSlug/), three sub-groups separated by dividers:

People:

  • Contacts (collapsible: Users, Teams — gated by ManageMembers | InviteMembers; Clients — ManageClients | InviteClients; Partners — ManagePartners | InvitePartners)
  • Workspaces — gated by CreateWorkspace | ManageWorkspaces

Integrations:

  • Connectors (collapsible: AI — ManageAiConfig; Storage — ManageOrgSettings; Email — ManageEmailConfig)
  • Usage (collapsible: AI Usage — ViewAiUsageHistory)
  • Email Templates — gated by ViewEmailTemplates

Admin:

  • Billing — gated by MANAGE_BILLING
  • Settings (collapsible: Profile, Address, Permissions — ManageSystemPermissions, Translations — ManageSystemPermissions)

Client Workspace Sidebar​

Rendered when workspacePurpose = CLIENT. Simplified view for external clients:

  • Dashboard
  • My Applications
  • Messages (with unread badge)
  • About [Org Name] section: Profile & About, Address & Contact

Personal Workspace Sidebar​

Rendered when workspaceType = PERSONAL:

GENERAL:

  • Dashboard
  • Applications

Account section:

  • Organizations
  • Billing
  • Settings (collapsible: Profile, Account, Appearance, Notifications, Display)
PersonaSidebar shownKey items
Owner / AdminStaffFull WORKSPACE + MANAGEMENT sections
Manager / MemberStaffWORKSPACE only; MANAGEMENT items filtered by permissions
Client userClient workspaceMy Applications, Messages, About org
PersonalPersonalDashboard, Applications, Account settings

What Happens on Org Creation​

When a user creates a new organization, the system automatically sets up the initial structure: