vite-press init

docs/en/design/architecture.md

@@ -0,0 +1,33 @@
+# Architecture
+
+OpenFlare consists of Server, Agent, and local OpenResty on each node.
+
+```text
+OpenFlare Server (Gin + SQLite/PostgreSQL + Web UI)
+        |
+        | HTTP API / Config Pull
+        v
+OpenFlare Agent (register / heartbeat / sync / apply / update)
+        |
+        v
+Local OpenResty or Docker OpenResty
+        |
+        v
+Origin
+```
+
+## Server
+
+`openflare_server` is a monolithic control plane based on Gin, GORM, SQLite/PostgreSQL, the existing login/session system, and the static frontend build.
+
+It owns the admin UI and API, Agent API, configuration rendering, version publishing, storage, and aggregate queries.
+
+## Agent
+
+`openflare_agent` is a single Go binary that runs locally on each node. It prefers `openresty_path` when configured and uses Docker OpenResty by default otherwise.
+
+It handles registration, heartbeat, sync, file writes, `openresty -t`, reload, rollback, self-update, and lightweight collection.
+
+## Frontend
+
+`openflare_server/web` is the production frontend baseline: Next.js App Router, React 19, TypeScript, and Tailwind CSS.

docs/en/design/development.md

@@ -0,0 +1,31 @@
+# Development Constraints
+
+After `1.0.0`, OpenFlare development prioritizes stability, upgrade and rollback reliability, documentation accuracy, test coverage, and small iterations inside the existing boundary.
+
+## Change Admission
+
+Before implementing a requirement, check:
+
+1. Whether it fits the product boundary.
+2. Whether it follows Server, Agent, and frontend development rules.
+3. Whether it risks the publish, sync, rollback, or upgrade flow.
+4. Whether deployment, configuration, or README docs need updates.
+
+If a requirement expands the boundary or introduces new infrastructure, update design documentation first.
+
+## Database Migrations
+
+Any table, index, column type, sharding, or internal persistence metadata change must bump the database version and include an explicit migration from the previous version.
+
+Migrations must validate the upgraded schema. Startup must stop if migration or validation fails.
+
+## Frontend Rules
+
+`openflare_server/web` is the frontend baseline:
+
+* Routes and layouts live in `app/`.
+* API calls are centralized under `lib/api/`.
+* Business logic belongs in `features/`.
+* Server state uses TanStack Query.
+* Forms use React Hook Form and Zod.
+* Theme supports `light`, `dark`, and `system`.

docs/en/design/index.md

@@ -0,0 +1,21 @@
+# Product Boundary
+
+OpenFlare is a self-hosted OpenResty control plane for single-team or single-organization operations. It unifies reverse proxy configuration, node synchronization, certificate management, and basic observability.
+
+Stable capabilities:
+
+| Capability | Description |
+| --- | --- |
+| Reverse proxy management | Site-level configuration with multiple domains and origins |
+| Configuration versions | Preview, publish, activate, and rollback |
+| Agent sync | Registration, heartbeat, sync, and apply result reporting |
+| OpenResty management | Main template, performance options, cache options, and Lua assets |
+| HTTPS/TLS | Certificate storage and per-domain binding |
+| Basic observability | Request rollups, resource snapshots, health events, and access analytics |
+| Node management | Node state, tokens, deployment, and update flow |
+
+Default operating model:
+
+* All nodes consume the same globally active version.
+* Server stores configuration and state, but does not SSH into nodes.
+* Agent is the only controlled entry point on each node.

docs/en/design/release-model.md

@@ -0,0 +1,33 @@
+# Release Model
+
+OpenFlare publishes complete configuration versions instead of modifying node configuration online.
+
+```text
+Edit rules -> Preview / diff -> Publish -> Create full version -> Activate -> Agent pulls -> Agent applies -> Agent reports
+```
+
+## Publish Rules
+
+Server must:
+
+1. Read all enabled `proxy_routes`.
+2. Read the OpenResty main template and structured options.
+3. Render the full OpenResty configuration.
+4. Compute `checksum`.
+5. Write `config_versions`.
+6. Switch the active version.
+7. Let Agents discover and apply it in later heartbeats.
+
+Version numbers use `YYYYMMDD-NNN`.
+
+## Immutable History
+
+Historical versions are immutable. Rollback reactivates an old version.
+
+Only one global active version exists at a time. Node-specific version groups are not part of the current model.
+
+## Agent Apply Strategy
+
+Agent backs up old files, writes the new main config, route config, certificates, and Lua assets, then validates and reloads.
+
+If activation fails, Agent attempts to recover. A failed `version + checksum` is blocked locally until the remote active version or checksum changes.