chore: initialize ZitPlane monorepo foundation
This commit is contained in:
commit
8f54ccb304
14 files changed
+222
No files matched your search
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user