planet/docs/technical/en/frontend-admin-frontend-context.md

Admin Frontend Context

This document describes the current real structure of the console frontend. The goal is to help future page development, table refactoring, layout governance, and state consolidation quickly find the right entry points.

Related references:

• Project Rules
• Frontend Layout Guidelines

Current Goal

The console frontend is a backend workbench, not a display-style dashboard. Current constraints:

• Pages default to a single-screen work area
• Primary interaction happens through in-module scrolling, not relying on the whole page growing infinitely
• Lists, tables, and analysis pages prioritize keeping the main work area visible
• Common layout, scrollbar, and table scroll behavior should be reused across pages

Current Route Entry Points

Main entry point:

• App.tsx

Current admin-related routes:

• /admin
• /users
• /datasources
• /data
• /alerts/system
• /alerts/bgp
• /alerts/situational
• /bgp
• /playground
• /settings

/earth is a standalone display page and is not part of the console shell.

Current Page Shell

The console shared shell is at:

• AppLayout.tsx

Responsibilities:

• Left-side navigation
• Collapse and expand
• Current account / version information
• Content area height closure
• Site-wide unified sidebar scrollbar

Current structure:

<Layout className="dashboard-layout">
  <Sider className="dashboard-sider">...</Sider>
  <Layout>
    <Content className="dashboard-content">
      <div className="dashboard-content-inner">{children}</div>
    </Content>
  </Layout>
</Layout>

Future console pages should adapt to this shell rather than redefining full-page height semantics.

Current Shared Components

1. Scrollbar

File:

• Scrollbar.tsx

Purpose:

• Ordinary content containers like the console sidebar
• Internally manages visibility, thumb size, drag, and dual-axis overflow detection

Current constraint:

• The scrollbar must be a floating overlay that does not participate in layout
• Should leave no visible trace when there is no overflow
• Real scrolling is still handled by the native container; only the visible layer and interaction layer are replaced

2. ScrollbarOverlay

File:

• ScrollbarOverlay.tsx

Purpose:

• Areas like Ant Table that already have an internal scroll container
• Does not take over scroll semantics; only adds a new scrollbar visible layer

Current usage:

• Data sources
• Collected data
• User management
• Settings page
• Alerts page
• BGP page

3. TableScrollRegion

File:

• TableScrollRegion.tsx

Purpose:

• Provides a unified wrapper for table scroll areas
• New table pages should reuse this rather than repeating the "table area + overlay scrollbar" boilerplate

4. SegmentedControl

Files:

• SegmentedControl.tsx
• SegmentedControl.css

Purpose:

• Segmented controls for language, theme, mode, or other 2 to 3 option settings
• Settings that need the shared animated slider, active state, and compact button layout
• The /docs footer language switcher and theme switcher already reuse it

Interface semantics:

• options: each option contains value and label, with optional icon and title
• value: current active value
• onChange: called when the selected option changes
• ariaLabel: accessible name for the control
• className: page-level hook for size or local style overrides

Current constraints:

• The component owns slider count, position, and spring-like transition
• Feature pages should only pass options and state, not recreate private slider DOM
• Prefer CSS variable overrides for colors instead of hard-coding theme colors in feature components
• Best for a small set of mutually exclusive choices; do not use it as a long list, navigation menu, or select replacement

5. MarkdownRenderer

File:

• MarkdownRenderer.tsx

Purpose:

• Renders Markdown content for /docs
• Supports headings, lists, blockquotes, code blocks, tables, and basic inline formatting
• Code blocks and tables reuse Scrollbar so horizontal content does not blow out the docs page

Current constraints:

• It is not a full GitHub Markdown engine; it only covers the syntax currently needed by project docs
• Internal document links should be converted to /docs/:slug through transformLink
• Heading anchors are injected through getHeadingId, keeping route state outside the renderer

6. TableActions

File:

• TableActions.tsx

Purpose:

• Shared action entry for table operation columns
• Shows inline actions when expanded
• Uses a more-actions dropdown when collapsed

Companion export:

• actionCellProps: for action-column onCell, preventing action buttons from being ellipsized or wrapped

Current State Sources

1. Auth State

File:

• auth.ts

Responsibilities:

• Token
• Current user
• Login / logout

App.tsx uses it to decide whether to redirect to the login page.

2. Business Data Gateway

AI / situational awareness related services are currently in:

• http-gateway.ts
• port.ts
• types.ts

Constraints:

• Pages must not scatter URL construction directly
• Define boundaries through port/types first
• Then implement via http/mock gateway

Current Page Layer Recommendations

1. Dashboard and Summary Pages

Example:

• Dashboard.tsx

Priority goals:

• Stable header
• Summary cards compact first
• Main work area occupies primary height

2. Table Pages

Examples:

• DataSources.tsx
• DataList.tsx
• Users.tsx
• Settings.tsx

Constraints:

• Prefer internal scrolling
• Do not let tables blow out the full page
• New table areas should reuse TableScrollRegion / ScrollbarOverlay

3. Complex Workspace Pages

Examples:

• BGP.tsx
• Playground.tsx

Constraints:

• Tab content must not share the same height logic
• Table tabs, Markdown tabs, and config tabs each need their own scroll responsibility
• AI result areas and long text areas should maintain a minimum readable height

Current Layout Constraints

These principles have been repeatedly validated in the project:

1. Parent container height chain must close
2. min-height: 0 must not be omitted
3. Overflow responsibility must be explicit
4. Do not use overflow: hidden to mask structural issues
5. Do not compress the main work area to make summary cards show completely
6. Custom scrollbars must be floating overlays; they must not squeeze content width

For detailed experience, see:

• Frontend Layout Guidelines

Recommended Change Approach

For future console page changes:

1. Confirm whether the page is a summary page, table page, or complex workspace
2. Integrate into the existing shell and scroll semantics first
3. Reuse shared scroll components
4. Handle visual and detail interactions last

Do not write local CSS patches first, then retrofit the structure.

Current Clear Boundary

The console frontend and the Earth frontend are not the same system:

• Console frontend: React + Ant Design workbench
• Earth frontend: independent native HUD system under public/earth

Therefore:

• Do not move Earth's HUD / animations / state machine directly into the console
• Do not force the console's table / scroll strategy onto the Earth HUD

For Earth-related structure, see:

• Earth Frontend Context