Atlas

Atlas is my reusable frontend platform and design-system foundation. It gives me a consistent way to build production-shaped web applications across SaaS dashboards, internal tools, developer products, client work, and Web3 interfaces without rebuilding the same application shell every time.

It is not a thin starter template or a Figma-only design system. It is a monorepo with shared packages, documented architecture, CI enforcement, and a demo application that proves the patterns work together in practice.

The reference app covers the parts that usually get rebuilt per project: authentication, typed data fetching, forms, feature flags, error tracking, theming, accessibility, and consent. The shared UI package holds the visual primitives and the interface-state components that make products feel finished under real conditions.

Why I built it

I kept paying the same tax on every frontend: folder structure debates, inconsistent HTTP patterns, fragile forms, and observability added after something breaks in production. That cost compounds when you move between product types and delivery timelines.

I built Atlas so I could spend more time on product logic and less time re-deciding infrastructure. The goal was a system where solid frontend engineering is the default path, not something I reconstruct for each codebase.

Architecture

Atlas is a pnpm workspace orchestrated with Turborepo. A Next.js App Router reference application shows how the platform fits together: thin routes, feature modules, shared infrastructure, and a composed provider shell.

Layering. Routes compose pages and layouts. Feature modules own domain logic, queries, mutations, and feature-specific UI. Shared infrastructure handles the API client, auth, telemetry, feature flags, and React Query utilities. Features do not import from other features.

Packages. A shared UI package holds components, form helpers, and theme utilities. A config package centralizes ESLint, TypeScript, Jest, and Prettier settings. An optional consent package wires cookie consent into analytics adapters.

Application shell. A root provider tree composes feature flags, theme, toasts, consent bridging, and Web Vitals reporting. An app layout pattern provides sidebar, header, and breadcrumbs for dashboard-style products.

Contracts. OpenAPI is the source of truth for client-server types. Generated TypeScript surfaces API drift during development instead of at runtime.

Design system and UX foundations

The UI package is built on Radix primitives and Tailwind CSS v4 with CSS-first design tokens. Storybook documents the component library.

The important layer is not just buttons and inputs. Atlas includes app-state primitives for the parts users actually feel: skeleton loading, empty states, recoverable errors, and accessible form field messaging.

Theming supports light, dark, and system modes. A pre-paint script applies the theme class before first render so hard reloads do not flash the wrong mode. Demo pages exercise keyboard navigation, focus behavior, and theme switching as integration work, not isolated component demos.

Data, auth, and observability

Data and forms. Feature modules expose typed React Query hooks built on a centralized API client. Query key factories keep cache invalidation predictable. Zod schemas align client and server validation, with server errors mapped back to individual fields.

Auth. Atlas implements OAuth 2.0 with PKCE. Tokens stay server-side. Sessions live in encrypted httpOnly cookies. ESLint blocks raw fetch() in UI layers and direct environment variable access in application code, keeping HTTP behavior centralized at API boundaries.

Observability. A proxy layer assigns correlation IDs to requests and passes them through logs, API errors, and response headers. Sentry is integrated across client, server, and edge runtimes. Web Vitals reporting is wired into the application shell. CI runs lint, typecheck, unit tests, build, and Playwright smoke tests, with bundle budget and Lighthouse workflows for performance regression checks.

Developer experience

Atlas is opinionated on purpose. New work follows a repeatable path: add a thin route, create a feature module, define query keys, wire typed hooks, and use shared UI states.

Public docs explain architecture and capabilities. Internal guides cover day-to-day implementation. Major decisions are recorded in ADRs covering theming, env validation, React Query, OAuth, Sentry, and consent.

Eight demo routes exercise platform primitives with mocked backends. The data demo supports URL-driven mode switching for loading, empty, error, and success states. That is integration evidence, not sample snippets in isolation.

Tradeoffs

Atlas reduces decision fatigue by narrowing choices. That is the point, but it is not the right fit for teams that want maximum flexibility over consistency.

The monorepo is structured for multiple applications, but only the reference app ships in the repo today. That keeps the platform focused, but adoption claims should stay grounded in how I actually use it.

CSP is configurable but off by default. RBAC is not implemented yet. Test coverage is real but not exhaustive. Those are known gaps I would close as the platform matures: broader flow tests, a second real application in the monorepo, stronger authorization patterns, and automated accessibility gates beyond linting.

Result

Atlas is how I turn messy product requirements into clean, production-shaped interfaces without rebuilding the same frontend foundation every time.

It shows I can design more than a component library. I can build platform infrastructure: monorepo boundaries, typed API contracts, enforced conventions, app-state UX, and a demo surface that proves the system works end to end.

That is the layer I want in place before feature velocity starts to matter.