Platform Map & Version Constraints

The stack you already run

You are not learning a new framework. You are learning how to make an AI CLI tool productive inside a framework you already know. That means the AI needs to understand the same constraints you do — version pins, endpoint patterns, file conventions, and the things that will fail a security review if done wrong.

This lesson maps the DS platform so you can encode it into a format AI tools consume automatically.

Platform stack reference

Azure Gov endpoints

Every Azure service you call uses a different base URL in Azure Government than in Azure Commercial. AI tools default to commercial endpoints. This table is the one your CLAUDE.md needs to enforce.

File structure

The DS platform follows Next.js App Router conventions with additional platform directories.

src/
  app/
    (auth)/           # Auth-required route group
      dashboard/      # Landing after login
      modules/        # Feature modules (each is a folder)
        [moduleName]/
          page.tsx    # Server Component — data fetching
          client.tsx  # Client Component — interactivity
    api/
      [moduleName]/
        route.ts      # API route handler
    layout.tsx        # Root layout — providers, theme, nav
    middleware.ts     # Auth + RBAC checks before route access
  lib/
    auth/             # MSAL config, session helpers, withPermission
    db/               # Azure SQL connection, query helpers
    swr-helpers.ts    # Shared fetchers, mutation wrappers
    response.ts       # listResponse(), errorResponse(), safeError()
  components/
    ui/               # MUI wrappers, shared presentational
    density/          # DensityGate, executive/operational/technical views
    navigation/       # AppBar, Sidebar, breadcrumbs
  types/
    rbac.ts           # Role enum, Permission type, PermissionMatrix
    modules.ts        # Module registration types
migrations/           # Azure SQL migration scripts (sequential)

CLAUDE.md as platform memory

AI CLI tools read a CLAUDE.md (or GEMINI.md, or .codex/instructions.md) file at the root of your project to understand constraints before generating any code. This is the single most impactful file you can create for AI-assisted development on a constrained platform.

The prompt

Open your AI CLI tool at the root of your project and paste this:

Generate a CLAUDE.md file for our Next.js platform. Here are the hard constraints:

Stack: Next.js 15.5 (App Router only, no Pages Router), React 19.1,
TypeScript 5.x strict mode, MUI 7, Tailwind CSS v4, Zod v3 (NOT v4),
next-auth v5 with JWT strategy, @azure/msal-node 2.x

Infrastructure: Azure Government cloud — all endpoints use
*.usgovcloudapi.net (NOT *.azure.com). Azure SQL via Managed Identity
(AAD token auth, never connection strings with passwords). Key Vault
for secrets. App Insights for telemetry.

Auth: @azure/msal-node with explicit
AzureAuthorityHosts.AzureGovernment authorityHost. next-auth v5 JWT strategy
with 8-hour max session (NIST AC-12). No database sessions.

RBAC: 5 roles — viewer, operator, manager, admin, superadmin.
withPermission() HOF wraps every API route. Middleware.ts enforces
route-level checks.

File conventions: Feature modules live in src/app/(auth)/modules/[name]/.
API routes in src/app/api/[name]/route.ts. Shared DB helpers in
src/lib/db/. Response helpers (listResponse, errorResponse) in
src/lib/response.ts. All API responses paginated with 500-item cap.

Testing: Vitest for unit/integration (Node env for server, jsdom
for components). Playwright for E2E.

Rules:
- Never generate Pages Router code (no getServerSideProps, getStaticProps)
- Never use *.azure.com endpoints — always *.usgovcloudapi.net
- Never use Zod v4 APIs (.pipe(), v4 error maps)
- Never put DB access in middleware (edge runtime can't run mssql)
- Never fabricate seed data that looks like real operational data
- Always use response helpers for API routes
- Always wrap API routes with withPermission()
- Always include data_source column in new tables

What you get

The AI produces a CLAUDE.md that every subsequent prompt in this project will respect. It typically runs 60-100 lines and covers stack versions, endpoint patterns, file conventions, and explicit prohibitions. Every AI tool that reads this file will generate code that fits your platform instead of fighting it.

See it in action

Here is what the interaction looks like when you ask the AI about your platform with the CLAUDE.md in place:

Notice the AI references Azure Gov endpoints and Zod v3 without being reminded. That is the CLAUDE.md doing its job.

What happens without CLAUDE.md

Without a platform memory file, the same prompts produce code that:

• Uses login.microsoftonline.com instead of login.microsoftonline.us
• Generates vault.azure.net URLs that time out in your gov subscription
• Suggests getServerSideProps for data fetching (Pages Router)
• Uses Zod v4 .pipe() chains that break at compile time
• Omits withPermission() from API routes, failing your next security review

You do not catch these errors at development time. You catch them in staging when the Azure AD token request fails, or worse, during a compliance audit when an unprotected route is discovered.

Key takeaways

• The platform map is your first deliverable. Before writing any feature code, encode your stack constraints into a CLAUDE.md that the AI reads automatically.
• Azure Gov endpoints are a different domain, not a different path. Every *.azure.com or *.azure.net reference must become *.usgovcloudapi.net. There is no fallback — commercial endpoints do not resolve in government subscriptions.
• Version pins are stability decisions, not technical debt. Zod v3, Next.js 15.5, and MUI 7 are pinned because they passed audit certification. The CLAUDE.md prevents AI tools from suggesting upgrades that would invalidate that certification.
• App Router only. Pages Router code (getServerSideProps, getStaticProps, pages/ directory) does not exist in this platform. Reject any AI output that contains it.

What’s next

In the next lesson, you will build the authentication layer: @azure/msal-node for Azure AD, next-auth v5 for session management, and the 8-hour session timeout required by NIST AC-12. The CLAUDE.md you just created will keep the AI on target for every file it generates.