Platform-Foundations

Platform Foundations is the shared foundation for PlainConcepts Platform apps. It keeps many independent apps consistent and easy for developers and AI agents to work in, without becoming a heavy in-house framework.

It covers the frontend (a shared theme, conventions, docs, and a themed showcase) and backend/.NET conventions (recommended skills and a reference architecture in ai/ARCHITECTURE.md).

It is not a component library, an app framework, or a design system to be maintained by hand.

What's here

ai/               ARCHITECTURE (incl. Stack) + DESIGN + AGENTS + .agents/ (skills, agents)
apps/docs         Fumadocs (Next.js), docs + live themed component previews
packages/theme    @plainconceptsplatform/ui-theme, design tokens (CSS only)
packages/ui-components  @plainconceptsplatform/ui-components, shared React components (Plain logo, ...)

Core principles

1. Prefer established open-source libraries over custom code.
2. Use shadcn/ui components directly; don't wrap them or build a proprietary library.
3. App-specific components live in the app. Share a component only after the same need appears in multiple apps.
4. The foundation owns the theme, conventions, docs, and showcase, nothing more.
5. Keep the scope small. Add a directory/package only when it has a clear job today.

Stack

Next.js (App Router) + React + TypeScript, shadcn/ui on Radix + Tailwind v4, themed by @plainconceptsplatform/ui-theme, icons from Lucide. DI via inversify-hooks (mandatory). Biome, Vitest + Playwright, pnpm. See ai/ARCHITECTURE.md.

Getting started (this repo)

pnpm install
pnpm dev          # run the docs/showcase site (Fumadocs)
pnpm lint         # Biome
pnpm test         # Vitest

Using Platform packages in your app

The Platform theme and shared components are private packages on GitHub Packages.

1. Configure registry access

Create a user-level .npmrc, not one in your app repository:

# Windows: %USERPROFILE%\.npmrc
# macOS/Linux: ~/.npmrc
@plainconceptsplatform:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_REGISTRY_TOKEN}

Create and authorize a personal access token as follows:

1. Open GitHub token settings and select Generate new token (classic).

2. Give the token the read:packages permission and generate it.

3. On the token list, select Configure SSO next to the new token and authorize PlainConceptsPlatform. This step is required by the organization’s SAML SSO policy.

4. Store the token in the NPM_REGISTRY_TOKEN user environment variable. For PowerShell on Windows:

   [Environment]::SetEnvironmentVariable('NPM_REGISTRY_TOKEN', 'YOUR_TOKEN', 'User')

   Open a new terminal before installing packages. Never add the token to a repository file. CI must inject NPM_REGISTRY_TOKEN from its secret store.

2. Install everything

pnpm add @plainconceptsplatform/ui-theme @plainconceptsplatform/ui-components tailwindcss

3. Initialize

npx @plainconceptsplatform/ui-theme@latest init

This copies components.json, adds the theme import to your global stylesheet, and shows you how to wire the Outfit font in your root layout.

4. Add shadcn components

npx shadcn@latest add button card dialog ...

Full details in packages/theme/README.md.

For AI agents

Start with AGENTS.md. It points to the ai/ folder, which has conventions, architecture, design rules, bundled skills, and agent definitions.

Documentation

• ai/ARCHITECTURE.md: reference architecture + stack (frontend and backend/.NET)
• ai/DESIGN.md: design tokens & UI rules
• packages/theme/README.md: theme package setup and conventions
• packages/ui-components/README.md: shared components (Plain logo)
• apps/docs/README.md: docs/showcase site structure