chore: initialize ZitPlane monorepo foundation
This commit is contained in:
commit
8f54ccb304
14 files changed
+222
No files matched your search
@@ -0,0 +1,12 @@
|
||||
root = true
|
||||
|
||||
[*]
|
||||
charset = utf-8
|
||||
end_of_line = lf
|
||||
insert_final_newline = true
|
||||
indent_style = space
|
||||
indent_size = 2
|
||||
trim_trailing_whitespace = true
|
||||
|
||||
[*.md]
|
||||
trim_trailing_whitespace = false
|
||||
+38
@@ -0,0 +1,38 @@
|
||||
# Secrets and local environments
|
||||
.env
|
||||
.env.*
|
||||
!.env.example
|
||||
!.env.*.example
|
||||
*.pem
|
||||
*.key
|
||||
*.p12
|
||||
*.pfx
|
||||
*.secret
|
||||
secrets/
|
||||
# Node / Next / tooling
|
||||
node_modules/
|
||||
.pnpm-store/
|
||||
.next/
|
||||
out/
|
||||
dist/
|
||||
build/
|
||||
coverage/
|
||||
.turbo/
|
||||
.nx/cache/
|
||||
*.tsbuildinfo
|
||||
# Tests and local data
|
||||
playwright-report/
|
||||
test-results/
|
||||
__pycache__/
|
||||
.pytest_cache/
|
||||
*.sqlite
|
||||
*.sqlite3
|
||||
*.db
|
||||
# Editors and OS
|
||||
.vscode/*
|
||||
!.vscode/extensions.json
|
||||
.idea/
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
Desktop.ini
|
||||
*.log
|
||||
@@ -0,0 +1,27 @@
|
||||
# ZitPlane — contributor and AI-agent instructions
|
||||
|
||||
## Project boundaries
|
||||
- Official ZITADEL Go backend is an external, version-pinned image. Do not vendor, fork or modify its core source.
|
||||
- `auth/ui/v2/` owns login frontend presentation; `users/ui/` owns the user portal.
|
||||
- Authentication, OAuth/OIDC callbacks, MFA, passkeys, sessions and token/security behavior are **protected logic**.
|
||||
- App-specific billing, product permissions, usage and license logic belong in the individual apps, not ZitPlane.
|
||||
|
||||
## Phase rules
|
||||
1. Inspect Git status and read `docs/PHASES.md` before editing.
|
||||
2. Require an explicitly approved scope before each new phase; stay within its exact allowed paths.
|
||||
3. Do not add fake runnable scaffolds, dependency versions, secret values or speculative upstream imports.
|
||||
4. On UI-only tasks edit components, styles and approved assets only; preserve auth flows and API contracts.
|
||||
5. Mock previews and test identities must be confined to development/test; never enable auth bypass in production.
|
||||
6. Run one focused verification, inspect exact diff, update relevant docs, and make one local Git commit per approved phase.
|
||||
7. Never push, deploy, create tags, access real user accounts or alter production without explicit approval.
|
||||
|
||||
## Security and portability
|
||||
- No credentials, master keys, database data, cert private keys, session tokens or `.env` in Git.
|
||||
- Production configuration must fail closed if required secrets, HTTPS or storage configuration are absent.
|
||||
- Lock external image versions and upstream Login V2 revision; document upgrade procedure.
|
||||
- Prefer readable React/TypeScript components, accessibility, responsive layouts and small reusable tokens.
|
||||
- Never modify upstream authentication machinery to accommodate an AI-generated UI without a separate security-approved scope.
|
||||
|
||||
## Developer experience
|
||||
- Keep README files accurate for the current phase. Do not claim an app runs before it is integrated.
|
||||
- Develop on local/test ZITADEL and synthetic users. Verify OIDC, MFA/passkey and redirect flows before release.
|
||||
@@ -0,0 +1,39 @@
|
||||
# ZitPlane
|
||||
|
||||
A compact, developer-friendly monorepo for central identity, branded sign-in, and account self-service.
|
||||
|
||||
**Status:** Phase 01 — repository foundation only. No backend, login app, account portal, or Docker stack has been installed yet.
|
||||
|
||||
## Planned components
|
||||
|
||||
| Path | Responsibility |
|
||||
| --- | --- |
|
||||
| `core/backend/zitadel/` | Version-pinned official ZITADEL backend configuration; **not** a copy of its Go source |
|
||||
| `auth/ui/v2/` | Customizable official Login V2 frontend, with required upstream build dependencies |
|
||||
| `users/ui/` | Separate account management portal |
|
||||
| `packages/` | Shared UI and generated/API clients, only when actually needed |
|
||||
| `deployment/` | Compose, reverse proxy, deployment configuration |
|
||||
| `scripts/` | Simple documented local developer entrypoints |
|
||||
| `tests/` | Focused integration and UI regression tests |
|
||||
| `docs/` | Architecture, development guide, phase scopes |
|
||||
|
||||
## Planned domains
|
||||
|
||||
- `auth.vib.tools` — ZITADEL OIDC/API, sign-in UI, built-in management console.
|
||||
- `account.vib.tools` — customer self-service account portal.
|
||||
|
||||
These domains are design targets; they are **not deployed or configured yet**.
|
||||
|
||||
## Ground rules
|
||||
|
||||
- One Git repository, multiple isolated Docker services at runtime.
|
||||
- ZITADEL stays upstream and version-pinned; no fork of its Go backend is planned.
|
||||
- Dev/prod data and credentials stay separate. No secrets in Git.
|
||||
- ZITADEL handles identity; individual SaaS products handle plans, billing and product data.
|
||||
- One approved, scope-locked phase at a time. See [phases](docs/PHASES.md) and [agent rules](AGENTS.md).
|
||||
|
||||
## Start here
|
||||
|
||||
1. Read [architecture](docs/ARCHITECTURE.md) and [development](docs/DEVELOPMENT.md).
|
||||
2. Approve Phase 02 before adding ZITADEL or any Docker startup configuration.
|
||||
3. Do not run an application from this foundation-only scaffold; none has been installed.
|
||||
@@ -0,0 +1,3 @@
|
||||
# Login V2 frontend
|
||||
|
||||
Reserved for a customized official ZITADEL Next.js Login V2. Phase 03 will select and pin an upstream commit, bring all required workspace dependencies, and verify the original behavior before any redesign. No UI source is installed yet.
|
||||
@@ -0,0 +1,3 @@
|
||||
# ZITADEL backend integration
|
||||
|
||||
Reserved for version-pinned **official ZITADEL image** configuration and setup instructions in Phase 02. No Go source vendoring or image download in Phase 01.
|
||||
@@ -0,0 +1,3 @@
|
||||
# Deployment
|
||||
|
||||
Future Docker Compose, Coolify routing, container health checks and secret-handling configuration. Production and development will use isolated databases and configuration. Nothing is deployed in Phase 01.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,3 @@
|
||||
# Shared packages
|
||||
|
||||
Reserved for reusable UI primitives/tokens and any upstream Login V2 client/proto dependencies actually required after source integration. Avoid speculative empty packages and dependencies.
|
||||
@@ -0,0 +1,3 @@
|
||||
# Scripts
|
||||
|
||||
Future beginner-friendly commands for local start/stop, focused verification and documented deployment checks. No scripts exist yet because the runtime has not been installed.
|
||||
@@ -0,0 +1,3 @@
|
||||
# Tests
|
||||
|
||||
Future focused smoke, OIDC integration, UI regression and security-boundary tests. Test identities only; do not call live production services without explicit approval.
|
||||
@@ -0,0 +1,3 @@
|
||||
# Account portal frontend
|
||||
|
||||
Reserved for a separate responsive Next.js self-service UI. ZITADEL remains the source of authentication and identity. Phase 04 will introduce the application with secure user-scoped APIs; there is no runnable portal yet.
|
||||
Reference in new issue
Block a user