Persona Flows¶

Two primary personas drive the frontend. Both authenticate against Microsoft Entra ID via the backend, then diverge based on permissions returned from the session endpoint.

Data-Entry User¶

Lab member who enters activity data for the unit they belong to and reviews the resulting emissions.

stateDiagram-v2
    [*] --> Login
    Login: LoginPage redirects to API_LOGIN_URL
    Login --> WorkspaceSetup: GET /v1/session succeeds
    Login --> Unauthorized: no view permission

    WorkspaceSetup: WorkspaceSetupPage (pick unit + year)
    WorkspaceSetup --> Home: workspace selected

    Home: HomePage (module overview)
    Home --> ModuleEntry: open a module
    Home --> ConsolidatedResults: open Results
    Home --> Simulations: open Simulations

    ModuleEntry: ModulePage (permissionGuard, meta.moduleEdit)
    ModuleEntry --> ModuleEntry: edit activity rows
    ModuleEntry --> ModuleResults: review module
    ModuleResults: ModuleResultsPage
    ModuleResults --> Home: back to overview
    ModuleResults --> ConsolidatedResults: open Results

    ConsolidatedResults: ResultsPage (all modules)
    ConsolidatedResults --> Home

    Simulations --> AddSimulation: create
    Simulations --> EditSimulation: edit existing
    AddSimulation --> Simulations: save
    EditSimulation --> Simulations: save

    Home --> Logout
    Logout --> [*]

Key gates:

• validateUnitGuard rejects unknown units in the URL.
• permissionGuard (via meta.moduleEdit) blocks read-only users from ModulePage while still letting them open ModuleResultsPage and ResultsPage.
• The workspace Pinia store holds the selected (unit, year) and survives page reloads via pinia-plugin-persistedstate.

Back-Office User¶

Admin who curates emission factors, manages users, edits documentation, and audits the system. Access is gated by backoffice.users permissions (scoped per affiliation — see issue #459).

stateDiagram-v2
    [*] --> Login
    Login --> BackOfficeShell: backoffice.users:view
    Login --> Unauthorized: missing permission

    BackOfficeShell: /back-office (redirects to Reporting)

    BackOfficeShell --> Reporting
    BackOfficeShell --> DataManagement: requires edit
    BackOfficeShell --> UserManagement: requires edit
    BackOfficeShell --> UITextsEditing
    BackOfficeShell --> DocEditing
    BackOfficeShell --> Logs: system.users:edit

    Reporting: ReportingPage (generate / monitor reports)

    DataManagement: DataManagementPage
    DataManagement --> ImportFactors: upload CSV
    ImportFactors --> ValidateFactors: backend validates
    ValidateFactors --> DataManagement: success
    ValidateFactors --> DataManagement: errors shown

    UserManagement: UserManagementPage (assign roles)

    UITextsEditing: UITextsEditingPage (i18n via GitHub PR)
    DocEditing: DocumentationEditingPage (docs via GitHub PR)

    Logs: LogsPage + components/audit/*
    Logs --> Logs: filter, paginate, drill down

    BackOfficeShell --> Logout
    Logout --> [*]

Key gates:

• Back-office routes declare meta.requiredPermission (one key per page, e.g. backoffice.users, backoffice.logs) enforced by permissionGuard; see frontend/src/router/routes.ts.
• The audit drawer (AuditDetailDrawer.vue) reads from components/audit/* and the backofficeDataManagement store.
• UITextsEditingPage and DocumentationEditingPage write changes by opening pull requests on the docs / i18n repo — no direct file writes from the browser.

Where Things Live¶

For the underlying request/response model, see Auth Flow Across Layers and Data Flow.