@sineforge/dashboard

The shared React administration dashboard interface for the Sineforge Backend-as-a-Service (BaaS) platform.

This package is the single source of truth for the project administration interface, shared and consumed by:

1. The local self-hosting app in /frontend of this repository.
2. The enterprise sineforge-cloud cloud-hosted dashboard.

Key Feature Modules

The dashboard is organized into focused React feature modules:

• Database Explorer: Interactive table schema designer, live spreadsheet-style records editor powered by react-data-grid, foreign key helper, and a SQL Editor console.
• Authentication: User profile table management, signup/login status controls, and third-party OAuth provider configurations.
• Storage Browser: Multi-bucket creation, file upload/download explorer, and S3-compatible cloud storage gateway settings.
• Edge Functions: Serverless edge functions code compiler, deployment manager, and live Deno application logs streaming interface.
• Model Gateway: Direct Model Gateway model catalog configuration, API key management, and live credit/token usage metrics charts.
• Compute Services: Fly.io container configuration, region selection, and CPU/memory resource allocation interface.
• Payments: Integrated Stripe Checkout session manager and customer Billing Portal.
• Analytics: KPI statistics, retention rates, and posthog traffic monitoring panels.

Console page responsibilities

These boundaries apply to every Sineforge module, including authentication, database, storage, realtime, functions, compute, and future integrations.

• Overview owns service status summaries. Render them through the shared features/dashboard/components/ServiceStatusSection.tsx in both overview variants and both hosting modes. Add a service only after its real availability check exists. State the coverage; a partial result must not imply that the entire instance is healthy. A successful metadata request means the API connection works, not that every service works.
• Module pages own configuration and task-specific feedback. Keep login methods, OAuth enablement, storage settings, and similar controls in their modules. Show dependency errors, validation failures, and repair actions beside the affected operation. Do not repeat a permanent service inventory or global health panel at the top of a configuration page.
• Capability discovery is an API contract, not a UI inventory. supported, enabled, and available have different meanings. Unsupported features and development milestones such as “not implemented yet” stay in planning docs and machine-readable discovery; do not render them as service rows or dead controls. An implemented but disabled or unconfigured service can be shown with its actual state and a link to its configuration. Failed checks must not display stale results as current availability.
• The overview summarizes; the module configures. Link status rows to the relevant module instead of creating another set of switches or settings. Keep probes in their services/hooks and preserve backend authorization checks.

Authentication follows the same ownership rule inside its module. Auth Methods owns first-factor addition/removal, the default method, MFA and method-specific configuration. Password rules appear only in the enabled password row's Configure dialog; Passkey, SMS and external providers use their own method dialogs. A method without independent options has no Configure button. Auth Settings contains only shared signup/redirect, session, flow, identity-schema and delivery/integration settings. Do not duplicate method enablement, password rules or MFA there, including an SMS sign-in switch in integrations. Shared code limits stay with flows because they also govern registration, recovery and verification. Save dialogs only submit the top-level fields they own, retaining revision checks and unchanged fields of the shared policy object.

Before adding a Console status or capability surface, check which task it serves, which page owns it, and what evidence supports each displayed state. Review both hosting modes and overview variants. Include a focused rendering regression for unsupported/loading/failure states and confirm that module pages have not gained another global summary. Product docs must name the actual destination page.

Currently the service summary covers Authentication and OAuth. Database, storage, realtime, and functions do not gain healthy indicators from metadata counts. Expand coverage as their real service probes are integrated.

Technology Stack

This package leverages the following frontend stack:

| Layer | Library / Tool | |---|---| | Core Framework | React 19 + TypeScript | | Data Fetching / Caching | TanStack Query v5 (React Query) | | Styling & Theme | Tailwind CSS 4.1 (dark-mode design system) | | Routing | React Router DOM 7 | | Code Editor | CodeMirror 6 (SQL, JavaScript, and JSON support) | | Data Visualizations | Recharts 3 | | Diagrams & Graphs | @xyflow/react 12 (interactive Schema ER diagrams) | | Real-time Engine | Socket.io Client 4.8 |

Monorepo Wiring

In this Turborepo workspace, @sineforge/dashboard is built as an independent, fully-typed NPM package.

sineforge/
├── frontend/             ← Mounts and serves the dashboard
│   ├── src/
│   │   ├── App.tsx       ← Thin router selecting cloud vs self-host mode
│   │   └── self-hosting/ ← Delegates full routing to @sineforge/dashboard
│   └── package.json      ← Declares dependency on "@sineforge/dashboard": "*"
│
└── packages/
    └── dashboard/        ← THIS PACKAGE
        ├── src/
        │   ├── features/ ← Feature-specific pages and components
        │   └── router/   ← Consolidated AppRoutes router mapping
        └── package.json

Dependency Boundaries

To maintain package isolation and clean separation of concerns, the @sineforge/dashboard package adheres to the following dependency boundaries:

• Internal Packages: Depends strictly on @sineforge/shared-schemas for data validation/contracts and @sineforge/ui for shared UI primitives and components.
• No Parent Dependencies: Does not import or depend on the parent hosting shells (frontend/ or enterprise cloud hosts). Configuration is passed down from the parent host at runtime via context providers.
• Service Isolation: Interacts with the sineforge-backend server exclusively via HTTP REST endpoints and Socket.io WebSocket connections. No direct database or server-side internal modules are imported.

Console and end-user credentials

Console admin sessions and Kratos end-user sessions can coexist in one browser. Send management requests through apiClient, including multipart uploads and binary downloads (requestStream), so bearer requests omit ambient cookies and retain token refresh and the host-configured API base URL. Do not combine an admin bearer with a Kratos cookie on resource APIs or relax their credential conflict checks to accommodate the Console.

Admin sign-in, authorization-code exchange, refresh, and logout explicitly use credentials: 'include' to receive, rotate, or clear admin session cookies. Public Kratos flows and OAuth consent use the end-user cookie session; keep their client separate from the Console bearer client. Check coexistence and refresh when changing either request path, in both hosting modes.

Release Expectations

Build output: Vite + tsc produce ESM under dist/, with dist/index.js and dist/styles.css declared via exports in package.json. Distribution: Currently consumed only via the monorepo workspace ("@sineforge/dashboard": "" in frontend/package.json). The package is not yet published to a public registry; the 0.0.0-dev. versions track internal iterations. Versioning: Will adopt SemVer once the package is published externally. Until then, treat any change as potentially breaking for host shells.

Local Development

Before developing, make sure you have installed the root monorepo dependencies:

# From the repository root:
npm install

Development Scripts

Inside packages/dashboard/, you can run the following package-specific commands:

# Run unit tests via Vitest
npm run test:unit

# Run component tests (Vitest + Testing Library)
npm run test:component

# Run end-to-end UI tests (Playwright)
npm run test:ui

# Type-check without emitting
npm run typecheck

# Verify code formatting and lint rules
npm run lint

# Compile and build the package
npm run build

Unit tests are written using @testing-library/react and Vitest to guarantee coverage of core feature pages, state-hooks, and form validators.

Passkey live authentication verification

npx playwright test -c packages/dashboard/playwright.auth-live.config.ts (repository root) is an opt-in development-instance suite, separate from mocked UI smoke tests. Set SINEFORGE_AUTH_LIVE=1, administrator credentials and the API/Console/Chat URLs as described in docs/core-concepts/authentication/passkeys.md. It exercises real Kratos with a Chromium virtual authenticator, temporarily changes auth settings, creates test users and cleans up afterward. HTTP localhost and HTTPS are supported; never target production. Traces and screenshots are disabled to avoid retaining authentication material.

Email OTP is added or removed under Authentication → Auth Methods. It has no separate configuration dialog; code expiry and attempts are shared across login, registration, recovery and verification and remain under Auth Settings → Flows. The hosted page renders code nodes independently from required password inputs, preserves CSRF, uses unique field IDs, and permits resend without an entered code. The opt-in tests/auth-live/email-otp.spec.ts checks hosted and Chat flows with real Kratos and Mailpit. Add SINEFORGE_MAILPIT_URL to the live-test environment. Optionally set SINEFORGE_TEST_KRATOS_POSTGRES_CONTAINER to the development PostgreSQL container to simulate older identities missing code credentials; this changes only the suite's temporary identity rows and requires Docker access.

Configurable sign-in and MFA

Auth Methods manages enabled first factors and a default presentation, initially email and password. Enabling another method allows the operator to select it as default and remove password. Default selection and removal use the shared settings revision; provider mutations and settings mutations share the backend lock. Credentials survive method removal. External login providers and OAuth server applications remain separate configuration surfaces. Service availability belongs on Overview.

The MFA section independently configures TOTP, security keys and recovery codes and selects optional, enrolled-user or all-user enforcement. Unenrolled users under all-user enforcement must retain access to settings enrollment; protected APIs, public whoami, OAuth authorization and Realtime revalidation require AAL2. The hosted and Chat flow renderers prioritize active verification challenges before the configured login preference.

tests/auth-live/auth-methods.spec.ts verifies actual default ordering, password removal, email-code login, all three MFA policies, enrollment, AAL2 and independent recovery-code controls. It also checks native password login and raw whoami token authentication across MFA policy changes. Run it against a selected development preview with SINEFORGE_AUTH_LIVE=1, the API/Console/Chat/Mailpit URLs and administrator environment variables. It creates temporary users and restores the original configuration.

Bifrost gateway administration

Self-hosted Model Gateway settings use /dashboard/ai/settings/:section with policy, routing, logs and advanced sections. Sineforge owns project governance, routing and logs. The advanced panel opens native Bifrost instance configuration on a separate origin using a single-use POST ticket. Only local self-hosted admins can launch it; Cloud project tokens and service API keys are rejected. Do not embed native gateway scripts on the Console origin or expose upstream admin credentials.

On narrow screens the settings page replaces both sidebars and provides a return link. All Console chrome uses the four locale bundles. The pinned Bifrost UI keeps upstream forms and translations; its small shell lives in deploy/bifrost/console. See docs/deployment/model-gateway.mdx for deployment and upgrade validation.