Application Details and Actions — SPEC

Start here → AGENTS.md · SPEC_INDEX.md · ARCHITECTURE.md.

Metadata

Evidence Rules

The app detail page, URL/analytics helpers, action APIs, stores/components, and tests define current behavior. The earlier add-bot plan was verified against this implementation.

Source Material Register

Overview

/applications/[appId] server-renders normalized application detail content and conditionally exposes actions such as bot addition, messaging, native integration connection, authorization removal, webhooks, embedded app access, and external links. React/Astro components use same-origin action APIs and concern-specific stores.

Purpose / Responsibility

Owns application-detail presentation and user actions tied to one catalog application; data source normalization, global auth, and webhook persistence remain elsewhere.

Stack

Astro dynamic page, Astro/React components, Nano Stores, same-origin APIs, adapter helpers, Vitest.

Folder / Package Structure

src/pages/applications/[appId].astro
src/components/
├── AppDetailsHero.astro
├── AppDetailsDescription.astro
├── AddBotModal.astro
├── EmbeddedAppModal.astro
└── RequiresAdminModal.astro
src/pages/api/{auth-status,check-authorization,rooms,create-membership,send-direct-message,validate-embedded-app-access}.ts

Key Files (source of truth)

Public Surface

Requires (dependencies)

Synchronized app lookup, auth/session, Webex/Hydra APIs, media helpers, stores/notifications, URL safety, analytics, middleware/CSRF.

Requirements

Design Overview

The page is SSR-first. Normalized application data selects component variants and action affordances. Complex action flows hydrate only their islands/stores. All protected calls go through App Hub APIs, which apply session/CSRF/input controls and proxy to upstream clients.

Data Flow

flowchart LR
  URL --> DetailPage --> SyncRead["Redis/sync lookup"]
  SyncRead --> View["SSR detail components"]
  View --> Action["React/modal action"]
  Action --> Store
  Action --> LocalAPI
  LocalAPI --> Auth --> Webex

Sequence Diagram(s)

sequenceDiagram
  participant U as User
  participant D as Detail UI
  participant A as App Hub API
  participant W as Webex
  U->>D: Add bot
  D->>A: GET rooms
  A->>W: authorized rooms
  W-->>A: rooms
  A-->>D: items
  U->>D: choose room / direct message
  D->>A: protected POST
  alt success
    A->>W: membership/message
    W-->>D: success
  else failure
    A-->>D: stable error
  end

sequenceDiagram
  participant B as Browser
  participant P as Detail page
  participant R as Synchronized catalog
  B->>P: GET /applications/:appId
  P->>P: validate identifier
  P->>R: lookup friendly/raw id
  alt found
    R-->>P: normalized application
    P-->>B: SSR detail + canonical metadata/actions
  else missing
    R-->>P: null
    P-->>B: current not-found response
  end

sequenceDiagram
  participant U as User
  participant M as Embedded app modal
  participant A as Access API
  participant S as Settings service
  U->>M: request launch
  M->>A: GET access for app id
  A->>A: session/token/app validation
  opt configured authenticated policy
    A->>S: evaluate user access
  end
  alt allowed
    A-->>M: allowed true
    M-->>U: launch
  else denied/error
    A-->>M: allowed false + reason
    M-->>U: remain closed/error
  end

Class / Component Relationships

classDiagram
  class DetailPage
  class DetailComponents
  class ActionModal
  class AppDetailsStore
  class RoomsStore
  class ApiRoutes
  DetailPage --> DetailComponents
  DetailComponents --> ActionModal
  ActionModal --> AppDetailsStore
  ActionModal --> RoomsStore
  ActionModal --> ApiRoutes

Use Cases

• UC-1 View: visitor opens friendly-ID URL → SSR detail/SEO/actions. Evidence: src/pages/applications/[appId].astro.
• UC-2 Add bot: authenticated user selects room or direct message → protected mutation → feedback. Evidence: src/components/AddBotModal.astro, src/pages/api/create-membership.ts, src/pages/api/send-direct-message.ts.
• UC-3 Launch/connect: eligible action passes access/auth gating → safe navigation or integration OAuth. Evidence: src/pages/api/validate-embedded-app-access.ts, src/pages/integration/[integrationId]/connect.ts.

State Model

appDetailsStore holds current app/loading/error/embedded-access; roomsStore holds room list, membership and direct-message action errors. Modal visibility is coordinated by modal/client scripts and store state where applicable.

Business Rules & Invariants

• The detail app is a normalized application from the synchronized catalog.
• Protected actions never send server tokens to the browser.
• URL targets and IDs are validated/encoded by helpers.
• Store/list state changes only after successful mutations.

Concurrency & Reactive Flow

• Room loading and action requests are async with distinct state fields.
• Duplicate action submission should remain disabled while pending.
• Media/authorization checks may run independently but must not overwrite unrelated errors.

State Machine

stateDiagram-v2
  [*] --> SSRReady
  SSRReady --> AuthRequired: protected action unauthenticated
  SSRReady --> LoadingAction: valid action
  LoadingAction --> Success: upstream success
  LoadingAction --> Error: validation/upstream failure
  AuthRequired --> SSRReady: login complete
  Error --> LoadingAction: retry
  Success --> SSRReady: dismiss

UI Flow

• Direct navigation shows server-rendered content or not-found.
• Actions display only for supported app capability/type.
• Modals expose loading, empty, validation, upstream error, and success states; focus/scroll behavior follows web-experience rules.

Error Handling & Failure Modes

Pitfalls

• App id, friendlyId, clientId, and bot username are different identifiers.
• Add-bot membership and direct-message paths have distinct payloads/failures.
• Do not use legacy route shapes such as product-prefixed application URLs.

Module Do’s / Don’ts

• DO use central URL/analytics/action helpers and same-origin APIs.
• DO preserve SSR detail content.
• DON’T infer capabilities from display text.
• DON’T optimistically claim upstream mutation success.

Key Design Trade-off

SSR detail pages maximize direct-navigation/SEO reliability, while selectively hydrated action flows add coordination complexity across components, stores, and protected APIs.

Test-Case Strategy (module)

Test URL/analytics helpers, auth/action API validation and status mapping, store transitions, modal/component states, SSR build, and authenticated E2E where service test users are available.

Traceability

• Architecture: ARCHITECTURE.md
• Security: SECURITY.md
• Coverage baseline: .sdd/manifest.json