The Atlas

Getting Started

The front door: what MikeOSS.Azure is, the three deployment paths (local Docker stack, manual Azure self-host, one-click marketplace), and the contributor invariants that keep the upstream fork mergeable. Start with README, then AGENTS.md, then the runbook for your path.

• Agent Guidance Read before editing storage, auth/config env vars, dynamic-route components, /install, or the backend boot sequence — these are the tripwires.
• Contributing Read before opening a PR to match the project's scope, review, and security-reporting expectations.
• Deploying Mike to Azure — minimal self-host Follow this to stand Mike up in your own Azure tenant the simple way, then use its production appendix as the hardening roadmap.
• Dev environment deployment runbook Reference when reproducing or auditing the Bicep-based Azure dev deployment and its exact resource names and ordering.
• Local development stack — step by step Use to get the whole stack running locally in local-auth mode for the fast inner-loop dev workflow.
• MikeOSS.Azure Start here to understand what the repo is and pick which of the three deployment paths you want.
• Runbook: Local Microsoft Entra ID Authentication Use to validate the real Entra sign-in flow on localhost without deploying any Azure infrastructure.
• Safe Local Testing Read before pointing Mike at any data or keys to avoid leaking real secrets or client documents during evaluation.

Migration Issues (PRD-by-PRD)

The PRD-by-PRD record of the migration: the numbered issues (001-040, with sub-issues) that took the Mike app off hosted Supabase and hosted LLMs and onto a customer's own Azure tenant - Bicep infra, PostgREST over Postgres, Azure Blob, Entra ID auth, the /install configurator, the marketplace package. Each is bound to the code it changed; read them in number order to follow the build.

• 001-bicep-infra-foundation Read first when standing up a fresh Azure environment, or when changing VNet topology, Private DNS, Key Vault, or the Bicep parameter contract that the other slices inherit.
• 002-acr-and-postgrest-mirror Read when setting up the container registry, upgrading the pinned PostgREST version, or adapting the deployment to a customer's existing ACR.
• 003-postgres-provisioning Read when provisioning or resizing the database, debugging private-endpoint/DNS connectivity, or deciding between the 5432 and 6432 connection paths.
• 004-schema-migration-tooling Read when adding or debugging a schema migration, understanding why RLS/triggers were dropped, or wiring the db-migrate job into a deploy.
• 005-storage-provisioning-and-blob-adapter Read when working on document upload/download, adding a new storage backend, or provisioning the blob account and its private endpoint.
• 006-cae-postgrest-backend-deployment Read when deploying or troubleshooting the live Container Apps stack, the internal PostgREST routing, Managed Identity role assignments, or cold-start scale-to-zero behaviour.
• 006.1-storage-provider-interface Read when preparing the upstream storage PR or reasoning about which storage changes are fork-only versus contributable to the OSS project.
• 006.2-auth-provider-interface Read when scoping the upstream auth-abstraction PR or distinguishing the contributable provider interface from the fork-only Entra implementation.
• 007-cicd-pipeline Read when authoring or changing the deploy workflow, the Dockerfile, or the OIDC/role setup that lets CI push and deploy without stored credentials.
• 008-backend-auth-provider-abstraction Read when touching auth middleware, adding a new identity provider, or understanding the provider-dispatch contract and the fork-delta ledger.
• 009-backend-entra-jwt-validation Read when implementing or debugging Entra token validation — JWKS caching, audience/tenant checks, the oid-to-userId mapping, or the group-overage handling that later gates access.
• 010-tenant-group-enforcement When you need to understand how Entra group membership maps to app roles and how tenant/group access is enforced before business logic runs.
• 011-user-bootstrap-and-profile-endpoints When tracing how a user profile row gets created on first login and which backend endpoints replaced the browser's direct PostgREST profile access.
• 012-frontend-userprofile-refactor When verifying that the browser no longer hits Supabase PostgREST for profile data and seeing how the signup page was retired for Entra workforce auth.
• 013-frontend-msal-auth-provider When you need the frontend MSAL wiring — config, env vars, silent refresh, and the AUTH_PROVIDER gate that keeps Supabase mode working.
• 014-postgrest-jwt-switch-to-jwks When you need the real (deviated) PostgREST auth model in entra mode and why JWKS/HMAC validation was dropped rather than switched, plus the Bicep array-literal bug fix.
• 015-managed-identity-db-auth When you need how the migration job and backend authenticate to Postgres via Managed Identity tokens and which Azure-side principal/grant setup it requires.
• 036 — Marketplace install gaps surfaced during 2026-05-12 install Read when fixing any marketplace install failure, or to cite a stable gap number (#1-#32) when planning a fix.
• 036a — Marketplace install: plan + alternatives Read before picking which install gap to fix next, or whenever a PR is tempted to delete a "now-unused" mode branch — this is where the additive/config-gate rule is set.
• 037 — Decouple migrate-job DB connection from `AUTH_PROVIDER` Read when the migration job fails on DB auth, or before changing how runMigrations.ts resolves its connection string.
• 038 — `/install` first-visit bootstrap without a token paste Read when working on /install access control or first-visit onboarding, or to understand why the bootstrap token is no longer the primary path.
• 039 — Provision Entra app registrations at Bicep deploy time Read when implementing or debugging deploy-time Entra provisioning, or to see how 038 and 039 layer (happy path vs restricted-tenant fallback).
• 040 — `/install` configurator UX gripes (live capture) Read when touching any /install configurator row, manifest entry, or its error rendering, or to find the concrete repro behind a specific install UX bug.
• Azure / Entra ID migration — issue index Read first to orient in the migration epic — to find which issue covers a topic, see what is done vs pending, or understand the numbering and dependency graph.
• Issue 007 — CI/CD pipeline implementation plan Read when actually wiring or debugging the dev CI pipeline, the OIDC setup script, or the image-pinned migration step — the concrete companion to the 007 spec.
• Issue 008.0 — local auth provider + full-stack local dev Read when setting up or debugging the full local Docker dev stack — local JWT minting, the Caddy/PostgREST bridge, Azurite, or the service_role wiring.
• Issue 015 — Managed Identity DB auth implementation plan When you want the step-by-step migration-job MI cutover plan, its rollout/validation sequence, and the token-TTL and port pitfalls.
• Issue 016 — Azure Marketplace Listing + Full Deployment Automation When working on Marketplace packaging, the deploy/update scripts, the CI pipeline, or the anonymous-pull public-ACR image-distribution decision.
• Issue 017 — Local-First Auth Boundary When setting up or understanding the local-only auth mode and the third AUTH_PROVIDER value alongside supabase and entra.
• Issue 018 — Frontend API Token Boundary When you need the single source of truth for how frontend components obtain and attach the auth token regardless of provider.
• Issue 019 — Frontend Hosted Dependency Isolation When you need the frontend to build without Supabase/AWS env vars or are deciding whether a hosted-service browser dependency can be removed.
• Issue 020 — Azure Blob Storage First, R2 Fallback Isolated When working on backend document storage, the Azure Blob/Azurite path, or the storage provider boundary that quarantines the R2/AWS fallback.
• Issue 021 — Backend PostgREST Client Boundary When you need the backend's single data-client seam for PostgREST or are planning to replace supabase-js without scattering changes through every route.
• Issue 022 — Frontend deployment to Azure When deciding how the frontend is built and hosted on Azure, or why it ships as a static export.
• Issue 023 — Install configurator (`/install` + downloadable scripts) When working on /install, the manifest/check model, bootstrap-token handover, or how config and secrets flow through Key Vault.
• Issue 024 — PostgREST Caddy Sidecar for Local-Prod Parity When investigating PostgREST routing, the /rest/v1 strip, or why the local Caddy gateway was removed.
• Issue 025 — Lock Down or Remove the PostgREST Diagnostics Page When deciding whether the diagnostics route is exposed in production or how its token gating works.
• Issue 026 — Surface Silent Frontend Fallbacks in Chat Flow When chat create/load fails silently, or when auditing the frontend for swallowed fetch errors.
• Issue 027 — MSAL Silent Token Refresh on the Frontend When users get logged out after about an hour, or when changing how Entra browser tokens refresh.
• Issue 028 — Move Backend API to `/api/*` Prefix When a frontend route 401s on hard refresh, or when reasoning about backend API mount paths and the SPA fallback.
• Issue 029 — Reconcile Bicep with the live Container App state When the Bicep templates disagree with live Azure state, or before running a full az deployment group create.
• Issue 030 — Custom domain for the backend Container App When wiring custom-domain support into /install, or how DNS, managed certs, and redirect-URI re-registration fit together.
• Issue 030 — Runtime Config Endpoint (kill `NEXT_PUBLIC_ENTRA_*`) When understanding how the frontend gets runtime config, why auth-provider.ts was deleted, or the /config and /auth/logout endpoints.
• Issue 031 — Comprehensive logging (server + client) When adding structured logging, request correlation, client error shipping, or App Insights wiring.
• Issue 031 — Supabase Placeholder Removal When a non-supabase build fails on missing supabase env vars, or how getSupabaseClient() lazy construction works.
• Issue 032 — Retire `frontend/.env.production` Read when wondering why no tenant-specific `.env` is tracked, or before touching the Dockerfile frontend build / NEXT_PUBLIC_API_BASE_URL plumbing.
• Issue 033 — `deploy.ps1` `NEXT_PUBLIC_API_BASE_URL` build-arg Read when editing deploy.ps1's image build, or debugging a deployed frontend whose API calls hit localhost.
• Issue 034 — Execute Tier A upstream PRs Read when about to open the upstream provider-boundary PRs, or to understand the Tier A step of the three-repo publication strategy.
• Issue 035 — First Tier B + Tier C publication windows Read before running a publication window, or to understand how the dev fork fans out into the public OSS and private deploy repositories.

PRDs

Product-requirement docs for discrete features (OSS-2/3/4): each a ticket (the brief) plus, where present, a spec (the detail). Smaller, feature-scoped counterparts to the migration issues - sharer-name resolution, post-sync cleanups, admin GDPR erasure.

• Feature: sharer display-name resolution (Entra) When implementing the sharer-name resolver, weighing the no-Graph Option A against the Graph-directory Option C, or needing the exact code and permission details.
• Harden sharer display-name resolution (Entra-native, no Graph) For the quick OSS-2 scope, acceptance criteria, and what is explicitly out of scope; read spec.md for the full analysis.
• OSS-3 — Odds and ends from the upstream-sync merge When picking up the post-upstream-sync cleanups — the CSP work, the dual-OpenAI-API dispatcher, or the frontend build fixes and their remaining runtime-verify tasks.
• OSS-4 — Admin-initiated erasure of an Entra user's app data (GDPR) For the quick OSS-4 scope, acceptance criteria, and the compliance sign-off dependency; read spec.md for the full design.
• Spec: Admin-initiated erasure of an Entra user's app data When building the admin GDPR-erasure endpoint — for the erasure cascade reuse, identifier resolution rules, audit logging, and the no-identity-deletion boundary.

Fork & Migration Strategy

How the fork is published without leaking proprietary deployment code: the three-tier model (Tier A upstream PRs, Tier B public OSS fork, Tier C private deploy repo) and the rules routing each file. fork-delta.md is the live list of files diverged from upstream - read it before any upstream rebase.

• Azure Migration Research Proposal For the historical big-picture rationale of the Azure target architecture and the early service-selection and cutover decisions.
• Configuration extraction and sanitization Before pushing any Tier B branch — to run the sanitization regex and confirm no internal tenant IDs, FQDNs, or resource names leak.
• Fork delta — files diverged from upstream When rebasing onto an upstream release or auditing the full set of fork-modified files and what each change does.
• Local-First, Upstream-Compatible Migration Strategy When you need the design philosophy behind the provider boundaries and local-first dev stack, or the local validation steps before deploying to Azure.
• Migration analysis — splitting this fork for AGPL publication Start here to understand the three-repo / three-tier publication model before reading any individual migration doc.
• Per-file classification When you need the authoritative tier for any specific diverged file, or the rationale behind an A/B/C assignment before publishing.
• Tier A — upstream PR plan When extracting the storage or auth refactors as clean upstream PRs, and you need the exact files to include/exclude and the acceptance tests.
• Tier B — public AGPL fork publication plan (Repo 2) When publishing or updating the public AGPL fork (Repo 2) — for the squash decision, commit message, exclusion list, and pre-push gates.
• Tier C — private deploy repo publication plan (Repo 3) When publishing or updating the private deploy repo (Repo 3) — for its squash commit, app-code-exclusion guarantees, and pre-push verification.
• Tier C — proprietary retention (rationale) When deciding whether a borderline Azure-flavoured file is proprietary (Tier C) or publishable (Tier B), or to justify why a file is withheld from the public fork.

Architecture

The code-verified system picture: ARCHITECTURE-ANALYSIS.md (topology, the request pipeline, the three-mode auth boundary, the deploy choreography, and honest doc-code divergences) and the auth-provider selection flow. The reading to do before editing anything load-bearing.

• Architecture & Technology Analysis Read first for a grounded, file-cited mental model of the whole system and to learn where the docs and code actually diverge.
• Auth Provider Selection Flow Read to understand how login routes the browser through the backend to Entra, and the reasoning behind keeping bearer tokens and hiding Google.

Infrastructure

The Azure platform decisions as ADRs: VNet + private-endpoint topology, Container Apps compute, Key Vault + Managed Identity for secrets and identity, the Bicep-and-manual provisioning split, and container images + observability. Backs infra/main.bicep and infra/modules/*.

• 001 — Network topology When changing the VNet, private endpoint, NAT Gateway, or why Postgres has no public IP.
• 002 — Compute platform When touching Container Apps config, ingress, scaling, or the migration job's compute.
• 003 — Secrets and identity When adding a secret, wiring a Key Vault reference, or reasoning about Managed Identity grants.
• 004 — Bicep and manual provisioning When provisioning a new environment, editing main.bicep parameters, or following the manual az runbook.
• 005 — Container images When changing image build/tag/mirror flow, ACR auth, or the PostgREST version pin.
• Infrastructure decisions When you need the infra design map or the target-architecture overview before diving into a specific ADR.

Data & Postgres

The data tier: the Postgres Flexible Server SKU choice, the PostgREST-over-Postgres access pattern (an unmodified supabase-js client repointed at bare PostgREST), node-pg-migrate schema migrations, and the Entra/Managed-Identity DB-auth handoff. Backs backend/migrations and backend/src/lib/supabase.ts.

• 001 — Database platform and SKU When picking or changing the Postgres SKU, storage, backups, or connection pooling/port choices.
• 002 — PostgREST and access pattern When reasoning about why PostgREST is self-hosted internally or how the browser/backend reach the database.
• 003 — Schema migrations When adding a migration, changing the migrate job, or understanding deploy-time schema application.
• 004 — EntraID hand-off When starting the EntraID auth migration or checking which DB items were deliberately deferred.
• Postgres migration decisions When you need the Postgres design map, the Supabase audit results, or the settled-vs-deferred checklist.

Auth & Entra

The Entra ID implementation in depth: JWT/JWKS validation, group-to-role mapping, tenant gating, and the /install OIDC operator flow - a deep-dive plus a task breakdown. Pair with issues 008-014 and 023/038.

• Entra ID Implementation Deep Dive Read for the intent and design decisions behind the Entra auth model before changing tenant/group/role logic.
• Entra ID PR-Ready Task Breakdown Read to see the task-level implementation plan and which files each piece of the Entra work maps to.

Storage

The blob-storage platform decision and the StorageProvider boundary that lets the same code run on Azure Blob (tenant) or R2/S3 (upstream), with the load-bearing mutating-vs-read split. Backs backend/src/lib/storage.ts.

• 001 — Blob storage platform When working on document upload/download, the storage provider abstraction, or blob account/network config.
• Storage decisions When you need the storage design map or the R2-to-Azure-Blob principles at a glance.

Email

The email-service design: the provider choice and where notification / transactional email fits - or is deferred - in the Azure footprint.

• 001 — Email service When building the first email-sending feature or deciding on the email provider/interface.
• Email decisions When you need the email design map or the defer-until-needed rationale.

Install & Deployment

Getting a deployment live and keeping it current: the production-hardening recipe, the marketplace package + republish runbook, and the operator-run /install PowerShell scripts. Backs marketplace/, scripts/install/, and the /install route.

• `/install` operator scripts Read when running, auditing, or hand-replicating the /install operator scripts (Entra apps, redirect URIs, AOAI, access revoke, install reset).
• Azure production-hardening backlog Use as the checklist to harden a deployment for real customer data or before a marketplace ship, and to understand the entra-mode DB trust model.
• Mike AI — Azure Marketplace package Read to understand the marketplace bundle contents and the anonymous public-ACR image-pull design before touching the package.
• scripts/install Read to understand what the scripts/install/ directory is for and how the configurator exposes its scripts.
• Updating the Marketplace Listing Follow this exact order whenever cutting and submitting a new marketplace release; release-images runs before package-marketplace.

Developer Tools

The documentation tools themselves - the Skills & Prompts Explorer and Repository Explorer READMEs, plus this Atlas's own build log. All three separate mechanical discovery from authored curation.

• Atlas doc-build log When you re-run the Atlas after the code or docs change, or want to know how current the curation is.
• Authoring spec — curated explorer data fragments
• Repository Explorer — MikeOSS.Azure
• Skills & Prompts Explorer — MikeOSS.Azure

History & Sessions

Point-in-time records kept for context, not maintenance: session logs, the v1 gap analysis, the agent runbooks, and the upstream-sync log. Indexed for search; their references to moved or removed files are history, not drift.

• Agent handoff — 2026-05-05
• Agent runbook — executing the migration
• Internal-only agent rules — tier classification and AGPL publication
• Marketplace re-publish — ARM-TTK pre-flight & cert-policy hardening
• scripts/qa — pre-publication checks
• Session 2026-05-07 / 2026-05-08 — V1 gap analysis + slice 9 ship
• Session summary — 2026-05-08 → 2026-05-10
• Upstream sync log