Skip to content
Documentation
ADRs
ATOMX
0001 - Authorization Demo+ Scope and Implementation Direction

0001 - Authorization Demo+ Scope and Implementation Direction

Andi Lamprecht Andi Lamprecht ·· 10 min read· Draft
ClassificationCONFIDENTIAL
OrganizationDroneUp
DateMarch 2026
StatusPending

2. Decision

Adopt the Demo+ authorization scope for stakeholder presentation and keep the current frontend interaction model as the reference implementation for the next phase.

This decision locks in:

  • requester-facing My Authorizations
  • approver-facing Authorization Review
  • full User Profile route from the sidebar user row
  • polygon drawing with live preview and post-draw editing
  • client-side PDF generation for approved authorizations
  • env-driven sidebar visibility for presentation control

The current frontend implementation is sufficient for demonstration and contract design. The next major step is to replace demo-state data with a dedicated backend regulatory-service and persistent storage without changing the user-facing workflow.

3. Context

The current implementation delivers a frontend authorization workflow inside the existing deployed shell. It is strong enough to present a coherent regulatory flow to stakeholders, but it is still a demo architecture. Real FAA or USS integration, durable persistence, and production review workflows remain out of scope for this phase.

The main architectural question was how much of the authorization workflow to include in the presentation build.

Options Considered

OptionIncludesExcludesRecommendation
AMy Authorizations, Review Queue, basic Profile, polygon draw, approve/declineFull waiver inventory, richer snapshots, backend-ready schemaNo
BA plus full profile fields, drones, devices, waivers, request snapshots, review history, demo PDF, richer frontend flowsReal FAA/USS integration, waiver wizard, uploads, KML importYes
CB plus waiver application wizard, uploads, notifications, recurring ops, external integrationsNothing importantLater phase

4. Why Demo+

  • It covers requester, reviewer, and profile experiences in one coherent workflow.
  • It is large enough to present a credible regulatory story to stakeholders.
  • It keeps the UI and data model aligned with a future production backend.
  • It avoids overcommitting to compliance-heavy integrations before backend contracts exist.

5. Delivered Experience

5.1 My Authorizations

  • Full map-based screen using the existing app shell
  • Left overlay list panel with:
    • search
    • Current / Future / Past filters
    • sort selector
    • result count selector
    • Request New Authorization CTA
  • Right detail panel with:
    • request summary
    • profile and waiver snapshot
    • airspace snapshot
    • status and history
    • PDF download for approved items
  • Selecting an item:
    • opens the right panel
    • shows the authorization polygon on the map
    • fits the map to the request area
  • Closing the detail panel fully deselects the item and closes cleanly

5.2 Request New Authorization

  • Opens in the left panel using the same visual language as the list panel
  • Includes these sections:
    • Profile Snapshot
    • Operation
    • Aircraft and Device
    • Area
    • Time and Review
  • Phone is populated from the user profile
  • Device is required and comes from the profile or device set
  • Submit stays disabled until validation passes
  • Left-side request panel width is increased for readability
  • Close button styling stays circular and visually stable

5.3 Drawing and Map Interaction

  • Start Drawing activates polygon capture
  • A floating Finish Drawing button appears over the map
  • Double-click also finishes the polygon
  • While drawing:
    • a live preview line is shown from the last placed vertex to the cursor
    • a filled preview polygon is shown between placed points
  • After drawing:
    • vertices can be dragged to refine the area
  • Clear Area resets the polygon
  • Esc cancels unfinished drawing
  • Map controls are shifted so they do not overlap the right detail panel

5.4 Authorization Review

  • Map-based reviewer flow using the same shell
  • Wider left queue panel with:
    • search
    • Pending / History mode toggle
    • history status filters
  • Right review panel with:
    • request details
    • profile completeness snapshot
    • waiver coverage
    • history
    • approval actions
  • Review actions supported:
    • approve
    • decline with reason
  • Selecting an item:
    • opens the right panel
    • shows the polygon on the map
    • fits the map to the selected area

5.5 User Profile

  • Opened by clicking the full sidebar user element, not only the avatar
  • Implemented as a full route
  • Page content is scrollable
  • Includes these sections:
    • Contact and Certificates
    • Drones
    • Devices
    • Waivers
  • Supports profile-linked management required by the demo flow

6. Demo Navigation and Presentation Controls

The app supports env-based visibility for each sidebar item independently.

Demo Default Sidebar State

  • visible:
    • My Authorizations
    • Authorization Review
  • hidden:
    • Main
    • Mission Console
    • Mission Manager
    • Vehicle Manager
    • Settings
    • Mission Planner

This keeps stakeholder demos focused while preserving the ability to re-enable other tabs through env flags.

7. Screen Schemas

7.1 My Authorizations 

┌──────────────────────────────────────────────────────────────────────────────┐
│ Global Header                                                               │
├──────────────┬───────────────────────────────────────────────────────────────┤
│ Sidebar      │ Map Canvas                                                   │
│              │                                                               │
│              │  Left Overlay Panel                                          │
│              │  - Title: My Authorizations                                  │
│              │  - Search                                                    │
│              │  - Filters: Current | Future | Past                          │
│              │  - Sort                                                      │
│              │  - Results selector                                          │
│              │  - Request New Authorization CTA                             │
│              │  - Authorization list                                        │
│              │                                                               │
│              │  Right Flyout                                                │
│              │  - Status                                                    │
│              │  - Request details                                           │
│              │  - Waiver snapshot                                           │
│              │  - History                                                   │
│              │  - PDF action                                                │
│              │                                                               │
│              │  Map Background                                              │
│              │  - Authorization GeoJSON                                     │
│              │  - Airspace overlays                                         │
│              │  - Fit to area                                               │
└──────────────┴───────────────────────────────────────────────────────────────┘

7.2 Request New Authorization 

┌──────────────────────────────────────────────────────────────────────────────┐
│ Same shell as My Authorizations                                             │
├──────────────┬───────────────────────────────────────────────────────────────┤
│ Sidebar      │ Map Canvas                                                   │
│              │                                                               │
│              │  Left Request Panel                                          │
│              │  - Profile Snapshot                                          │
│              │  - Operation                                                 │
│              │  - Aircraft and Device                                       │
│              │  - Area                                                      │
│              │  - Time and Review                                           │
│              │  - Submit / Close                                            │
│              │                                                               │
│              │  Map Controls                                                │
│              │  - Start Drawing                                             │
│              │  - Floating Finish Drawing                                   │
│              │  - Double-click to finish                                    │
│              │  - Clear Area                                                │
│              │  - Live line preview                                         │
│              │  - Live fill preview                                         │
│              │  - Drag points after draw                                    │
└──────────────┴───────────────────────────────────────────────────────────────┘

7.3 Authorization Review 

┌──────────────────────────────────────────────────────────────────────────────┐
│ Global Header                                                               │
├──────────────┬───────────────────────────────────────────────────────────────┤
│ Sidebar      │ Map Canvas                                                   │
│              │                                                               │
│              │  Left Queue Panel                                            │
│              │  - Title: Authorization Review                               │
│              │  - Search                                                    │
│              │  - Filters: Pending | History                                │
│              │  - History status chips                                      │
│              │  - Requested authorization list                              │
│              │                                                               │
│              │  Right Review Flyout                                         │
│              │  - Request summary                                           │
│              │  - Profile completeness snapshot                             │
│              │  - Waiver coverage                                           │
│              │  - Approve                                                   │
│              │  - Decline                                                   │
│              │  - Decline reason modal                                      │
└──────────────┴───────────────────────────────────────────────────────────────┘

7.4 User Profile 

┌──────────────────────────────────────────────────────────────────────────────┐
│ Global Header                                                               │
├──────────────┬───────────────────────────────────────────────────────────────┤
│ Sidebar      │ User Profile Page                                            │
│              │                                                               │
│              │  Summary section                                             │
│              │  - Avatar, name, org, role                                   │
│              │  - Completeness indicators                                   │
│              │                                                               │
│              │  Scrollable content                                          │
│              │  - Contact and Certificates                                  │
│              │  - Drones                                                    │
│              │  - Devices                                                   │
│              │  - Waivers                                                   │
└──────────────┴───────────────────────────────────────────────────────────────┘

8. Workflow Diagrams

8.1 Experience Flow 

    flowchart LR
  A["Sidebar: My Authorizations"] --> B["My Authorizations Page"]
  B --> C["Select Authorization"]
  C --> D["Right Detail Panel"]
  D --> E["Map Fits To GeoJSON"]

  B --> F["Request New Authorization"]
  F --> G["Left Request Panel"]
  G --> H["Start Drawing"]
  H --> I["Live Line + Filled Polygon Preview"]
  I --> J["Finish Drawing Or Double Click"]
  J --> K["Adjust Vertices"]
  K --> L["Submit Request"]

  M["Sidebar: Authorization Review"] --> N["Review Queue"]
  N --> O["Select Request"]
  O --> P["Right Review Panel"]
  P --> Q["Approve Or Decline"]

  R["Sidebar User Row"] --> S["User Profile"]

8.2 Authorization State Model 

    stateDiagram-v2
  [*] --> DraftClient
  DraftClient --> Submitted : "Submit request"
  Submitted --> UnderReview : "Queued for review"
  Submitted --> Cancelled : "Requester cancels"
  UnderReview --> Approved : "Approve"
  UnderReview --> Declined : "Decline"
  UnderReview --> Cancelled : "Requester cancels before decision"
  Approved --> Expired : "End time passes"
  Declined --> [*]
  Cancelled --> [*]
  Expired --> [*]

9. Production-Oriented Data Model 

    erDiagram
  REGULATORY_PROFILE ||--o{ PROFILE_DRONE : owns
  REGULATORY_PROFILE ||--o{ PROFILE_DEVICE : owns
  REGULATORY_PROFILE ||--o{ PROFILE_WAIVER : owns
  REGULATORY_PROFILE ||--o{ AUTHORIZATION_REQUEST : submits
  PROFILE_DRONE ||--o{ AUTHORIZATION_REQUEST : used_by
  PROFILE_DEVICE ||--o{ AUTHORIZATION_REQUEST : used_by
  AUTHORIZATION_REQUEST ||--o{ AUTHORIZATION_HISTORY : records
  AUTHORIZATION_REQUEST ||--o{ AUTHORIZATION_DOCUMENT : stores
  AUTHORIZATION_REQUEST ||--o{ AUTHORIZATION_REQUEST_WAIVER : references
  PROFILE_WAIVER ||--o{ AUTHORIZATION_REQUEST_WAIVER : linked_to

  REGULATORY_PROFILE {
    uuid id PK
    string user_id UK
    string org_id
    string first_name
    string last_name
    string email
    string phone_e164
    string operation_category_default
  }

  PROFILE_DRONE {
    uuid id PK
    uuid profile_id FK
    string nickname
    string manufacturer
    string model
    string faa_registration_number
    string serial_number
  }

  PROFILE_DEVICE {
    uuid id PK
    uuid profile_id FK
    string label
    string device_type
    string manufacturer
    string model
    boolean is_default
  }

  PROFILE_WAIVER {
    uuid id PK
    uuid profile_id FK
    string waiver_type
    string waiver_number
    timestamptz valid_from
    timestamptz valid_to
    string status
  }

  AUTHORIZATION_REQUEST {
    uuid id PK
    uuid profile_id FK
    uuid drone_id FK
    uuid device_id FK
    string requester_user_id
    string operation_category
    jsonb area_geojson
    string timezone
    timestamptz start_at
    timestamptz end_at
    int requested_altitude_ft
    int approved_altitude_ft
    string status
    string authorization_number
  }

10. Field Coverage

10.1 Profile Fields

  • Identity:
    • first name
    • last name
    • email
    • phone
    • account type
    • organization name
    • organization type
    • DOB
    • citizenship
    • address
    • notification preferences
  • Certification:
    • operation category default
    • remote pilot certificate
    • TRUST certificate
  • Drones:
    • nickname
    • manufacturer
    • model
    • FAA registration number
    • serial number
    • weight
    • remote ID fields
  • Devices:
    • label
    • type
    • manufacturer
    • model
    • serial number
    • default state
  • Waivers:
    • waiver type
    • waiver number
    • valid from
    • valid to
    • status
    • notes

10.2 Authorization Request Fields

  • Operation:
    • operation category
    • purpose of flight
    • organization snapshot
    • requester phone snapshot
  • Area:
    • polygon GeoJSON
    • bbox
    • centroid
    • location label
    • optional enrichment snapshots
  • Time:
    • flight date
    • start time
    • end time
    • timezone
    • day or night flag
  • Review Result:
    • status
    • authorization number
    • requested altitude
    • approved altitude
    • conditions
    • decline reason
    • reviewer
    • timestamps

11. Current Frontend Architecture

Implemented Now

  • React + TypeScript + Vite
  • UnifiedMap for the map shell
  • shared left and right overlay panel patterns
  • demo regulatory state managed in Zustand
  • shared authorization components for:
    • detail panel
    • request panel
    • status badge
    • map layers
    • decline modal
  • seeded presentation data for:
    • requester authorizations
    • review queue
    • drones
    • devices
    • waivers
    • multiple polygons

Important UI Decisions Already Implemented

  • custom polygon drawing instead of a generic drawing plugin
  • map controls offset from right-side panels
  • full-row user profile entry in the sidebar
  • wider left panels for list and request modes
  • better long-text handling in stacked horizontal layouts
  • demo PDF generation from the detail panel

12. Target Backend Architecture

Recommended Next Step

Create a dedicated regulatory-service.

Rationale

  • inventory data and regulatory workflows are different bounded contexts
  • request snapshots and review history should not live in frontend-only state
  • the current UI is stable enough to drive backend contract design

Proposed API Surface

  • ProfileService.GetMyProfile
  • ProfileService.UpsertMyProfile
  • ProfileService.ListDrones
  • ProfileService.CreateDrone
  • ProfileService.UpdateDrone
  • ProfileService.DeleteDrone
  • ProfileService.ListDevices
  • ProfileService.CreateDevice
  • ProfileService.DeleteDevice
  • ProfileService.SetDefaultDevice
  • ProfileService.ListWaivers
  • ProfileService.CreateWaiver
  • ProfileService.UpdateWaiver
  • ProfileService.DeleteWaiver
  • AuthorizationService.ListMyAuthorizations
  • AuthorizationService.GetAuthorization
  • AuthorizationService.CreateAuthorizationRequest
  • AuthorizationService.ListReviewQueue
  • AuthorizationService.ReviewAuthorizationRequest
  • AuthorizationService.CancelAuthorizationRequest

Contract Decisions

  • store snapshots on the authorization request
  • no persisted drafts in v1
  • authorization number is generated on approval
  • decline requires a reason code
  • approval is binary in v1
  • review actions are limited to supervisor or admin roles

13. Database Direction

Proposed Tables

  • regulatory_profiles
  • regulatory_profile_drones
  • regulatory_profile_devices
  • regulatory_waivers
  • authorization_requests
  • authorization_request_waivers
  • authorization_request_history
  • authorization_documents

Storage Notes

  • PostgreSQL is recommended
  • store geometry as jsonb first
  • add PostGIS later if overlap or spatial querying becomes necessary
  • add indexes for:
    • user_id
    • request status
    • requester and time
    • reviewer and updated time

14. Risks and Decision Locks

Locked Decisions

  • do not overload inventory with regulatory workflows
  • do use request snapshots instead of live joins
  • do use custom map drawing behavior

Key Risks

  • missing profile phone or default device blocks request creation
  • removing linked drones or devices must be prevented for active or future requests
  • night operations need waiver coverage logic for credibility
  • real FAA or USS integration still requires separate backend work and policy decisions

15. QA and Readiness

Current Readiness

The current demo implementation passes:

  • yarn lint
  • yarn prettier
  • yarn stylelint
  • yarn test

Covered Areas

  • sidebar visibility behavior
  • authorization selection and deselection
  • request flow validation
  • drawing interaction
  • review actions
  • user profile navigation
  • PDF generation

16. Consequences

What This Enables Now

  • a coherent stakeholder demonstration of the authorization workflow
  • backend contract design without reworking the frontend experience
  • a clear separation between presentation-ready behavior and future production services

What Remains Out of Scope

  • real FAA integration
  • real USS integration
  • waiver wizard flows
  • uploads and KML import
  • recurring operations and notifications

17. Presentation Summary

We now have a working Demo+ authorization experience embedded in the current frontend shell. It supports requester and reviewer flows, profile management, map-based drawing and editing, and demo PDF output. The frontend interaction model is ready for stakeholder review. The next major implementation phase is replacing the demo store with a real regulatory-service and database-backed APIs without changing the user-facing workflow.

Last updated on
0002 - Mission Service as Talos Backend