Skip to content

Latest commit

 

History

History
50 lines (35 loc) · 3.74 KB

DESIGN.md

File metadata and controls

50 lines (35 loc) · 3.74 KB
Raw

Design

The guiding principle of Beehive is that it's a UI for Sherlock. It's part of the DevOps platform, not part of Terra.

Sherlock is thoroughly tested and carefully designed. To be blunt, the standards here are lower. UI work isn't our team's specialty, so a lot of Beehive's design is about Beehive not doing things. Some examples:

  • Beehive doesn't include any significant business logic: if we care about the behavior, we write it in Sherlock
  • Beehive doesn't handle authentication or authorization: it runs behind Identity Aware Proxy and passes that through to Sherlock
    • This behavior is actually one of the only areas where we currently have automated tests for Beehive
  • Beehive doesn't define models or many types at all: we rely on Sherlock's TypeScript client library
  • Beehive doesn't manage state, routing, or data loading: we use Remix
  • Beehive doesn't have custom CSS wherever possible: we use Tailwind

Architecture

The DevOps platform is currently being re-architected for improved security. The existing architecture diagram is here.

The summary is that Beehive and Sherlock run in the same clusters, with their respective ingresses configured with the same Identity Aware Proxy. Beehive passes requests to Sherlock post-IAP inside the cluster. Sherlock handles authentication and authorization.

Beehive truly runs inside the cluster: Remix integrates both backend and frontend. Remix's docs have more info.

Repository Layout

  • ./app/assets: Static assets for Remix to bundle and cache-bust
  • ./app/components: General-purpose reusable components matching Beehive's styling
  • ./app/errors: Error handling components and helpers
  • ./app/features: Components and helpers for specific features, e.g. ./app/features/sherlock/environments for Sherlock environments
  • ./app/helpers: Helper functions, primarily for use server-side
  • ./app/hooks: Custom React hooks
  • ./app/routes: One file for each page Beehive serves
  • ./app/styles: CSS for Remix to handle with PostCSS and cache-bust
  • ./app/themes: theme-specific CSS for Remix to bundle and cache-bust

./app itself contains execution entrypoints for both client and server, but it's root.tsx generally makes more sense as the starting point for the application.

Stack

  • TypeScript: Remix has good support for it and we inherit from Sherlock's types
  • NPM: We don't need complexity offered by anything else
  • React: Standard in DSP
    • TSX Syntax: All available documentation for other parts of the stack all used TSX (and it's become more standard in DSP since)
  • Remix: Framework pairing perfectly with Sherlock and its hierarchical model structure
  • Tailwind: Good-enough styling and flexibility coupled with excellent documentation for a team that isn't concerned with CSS
  • Lucide: Good-enough collection of tons of icons coupled with excellent documentation for a team that isn't concerned with graphic design

Themes

Themes aren't just a vanity feature, they're actually a core part of how Beehive helps folks avoid accidental modifications to production -- the theme will flip from light mode to dark mode or vice-versa when moving into a part of the app that directly impacts production.

There's more information available in ./app/themes.