chore: initialize ZitPlane monorepo foundation

This commit is contained in:
Vib Tools committed 2026-11-22 03:54:02 -08:00
commit 8f54ccb304
14 files changed
+222

No files matched your search

+30
View File
@@ -0,0 +1,30 @@
# ZitPlane architecture (proposed)
## Responsibility
ZitPlane is a central **identity and account-management platform**, not a billing or SaaS business backend.
- **ZITADEL** (official Go server): identities, authentication, OIDC, security policies, projects, admin console.
- **Login V2** (customized upstream Next.js app): branded signup, sign-in, recovery and challenge screens.
- **Account portal** (custom Next.js app): user-scoped profile/security/linked identities.
- **PostgreSQL**: persistent ZITADEL storage. Do not expose directly to the Internet.
- **Coolify / Compose**: one Git deployment definition, isolated services and persistent volumes.
## Production routing (target, not configured)
- `https://auth.vib.tools/`: ZITADEL OIDC discovery, OAuth/OIDC, API and management console; login routes must explicitly proxy to Login V2.
- `https://account.vib.tools/`: independent account portal using standard OIDC login.
- Clean `/login` is a **target route** requiring matched login app routes, ZITADEL Login Base URI and proxy; never assume a proxy rewrite alone is sufficient.
- Verify reverse-proxy h2c/HTTP2 needs, cookies, OIDC callbacks, CSRF and WebAuthn relying-party/domain behavior before release.
## Source ownership
- Do **not** copy the complete ZITADEL backend Go tree into `core/backend/zitadel/`; use immutable/version-locked official image and maintain deployment config here.
- Import compatible official Login V2 sources at a **single upstream commit**, including required workspace packages, generated clients/proto and lockfiles. The final layout may be adjusted to preserve upstream build integrity; document it before implementation.
- Share only presentation components/tokens across login and account projects unless explicitly approved. No shared browser-side admin credentials.
## Environments
- Development: local Docker PostgreSQL/ZITADEL, non-production test identities; Next.js hot reload; optional mock-only UI preview.
- Production: dedicated persistent PostgreSQL, protected secrets, hardened ZITADEL configuration, built Next.js apps, HTTPS, backups, health checks and controlled updates.
- Local dev settings and production config must never share databases, master keys or user records.
- A production Docker stack is not automatically secure simply because `NODE_ENV=production` is set.
## SaaS applications
Each external SaaS authenticates through ZITADEL using OIDC authorization code + PKCE when appropriate and validates tokens on its backend. Each app owns its own billing, subscription, business database, API keys and entitlement enforcement. Key users by stable issuer + subject identity, not email.
+25
View File
@@ -0,0 +1,25 @@
# Developer quick guide
**Current phase:** Foundation only. No `npm install`, Docker build or login preview is available yet.
## Where to make changes (after later phases)
- Login / signup / password recovery appearance: `auth/ui/v2/`.
- Account dashboard appearance: `users/ui/`.
- Reusable color tokens and components: `packages/` (only after created).
- ZITADEL image/config, not Go application code: `core/backend/zitadel/`.
- Compose, HTTPS routing and service configuration: `deployment/`.
## Planned local development
1. Install Git, Node.js with compatible pnpm and Docker Desktop.
2. Start a **local-only** ZITADEL + PostgreSQL stack using a later phase's documented script.
3. Start Login V2 and Account UI in Next.js development mode (hot reload).
4. Use test accounts, synthetic profile data and local-only UI states.
5. Inspect mobile/desktop, keyboard accessibility and full auth flows before any production build.
Commands, required versions and ports will be documented when the real upstream dependencies are installed. Do not guess them from this scaffold.
## Working with AI Studio / coding agents
Ask for changes scoped to JSX/TSX, CSS and design tokens. Review the resulting diff before integrating. Never paste generated mock auth, fake JWT handlers or browser-side admin API credentials into production. Protected auth/route code requires separate approval and focused security testing.
## Deployment rule
Coolify must use an explicit, production-safe Compose configuration. Local overrides and secrets must not be copied into production. Production deploy is not part of Phase 01.
+30
View File
@@ -0,0 +1,30 @@
# Phase register and scope locks
Only **Phase 01** is approved for implementation in this session. Each later phase requires its own explicit approval and exact scope lock.
## P01 — Foundation
- **Allowed writes:** `README.md`, `AGENTS.md`, `.gitignore`, `.editorconfig`, `docs/**`, and README placeholders under `core/backend/zitadel/`, `auth/ui/v2/`, `users/ui/`, `packages/`, `deployment/`, `scripts/`, `tests/`.
- **Action:** Create compact repository structure; configure repository-local Git identity (Vib Tools / hello@vibtools.io); create initial local main-branch commit.
- **Excluded:** Backend source/image download, dependencies, UI code, Compose deployment, secrets, external Git pushes, builds.
- **Acceptance:** Repository tree and Git identity confirmed; no unexpected files; clean worktree after commit.
## P02 — ZITADEL local backend (proposed; NOT approved)
- **Write scope to approve:** `core/backend/zitadel/**`, `deployment/docker/compose.backend.dev.yaml`, `.env.example`, backend-focused `tests/**`, and narrowly `docs/**` / `README.md`.
- Pin official image version/digest, local PostgreSQL and persistence, safe bootstrap + local test admin, startup/health checks. No Go backend vendoring.
- No public domain, Coolify deploy, real users, Login V2 import, new UI or production master keys.
- Focused acceptance: local startup + admin console reachability, persistence after restart, and clean shutdown; document exact lock and versions.
## P03 — Login V2 import (proposed)
Import one compatible official upstream commit including required workspace/dependencies under approved paths; unmodified functional baseline; verify one build and baseline auth route. No visual redesign.
## P04 — Account portal foundation (proposed)
Implement OIDC-protected basic user self-service skeleton under `users/ui/`; no fake production authentication.
## P05 — Integration (proposed)
Local development workflows, shared design tokens as needed, production-safe Compose topology, routing drafts, tests and docs. No live deployment.
## P06 — UI redesign (proposed)
Compact login and account UI, accessibility, responsive design and scoped visual regression. No change to protected authentication semantics.
## P07 — Production deployment (proposed)
Coolify, secured external domains, HTTPS, secrets, backups, persistent volumes and focused end-to-end readiness checks; only on explicit approval.