From 06fd31576acaa05cae624802a215d5449ca50168 Mon Sep 17 00:00:00 2001 From: siujamo Date: Tue, 1 Sep 2026 10:57:45 +0800 Subject: [PATCH] docs: reframe Helix as a quick-start boilerplate for customisation --- AGENTS.md | 13 +++++++++++++ CONTRIBUTING.md | 19 ++++++++++++++++--- README.md | 38 +++++++++++++++++++++++++++++--------- 3 files changed, 58 insertions(+), 12 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b9ebbe4..ef30b71 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,6 +3,13 @@ Guidance for AI coding agents and contributors working in this repository. It complements [README.md](README.md); read that first for the project overview. +> **Scope — this is a quick-start boilerplate.** Helix is a starting point for +> custom development, not a finished product. The baseline modules +> (authentication, RBAC, user/role/department/position/menu management) are +> intentionally kept minimal and exist to be extended. When adding features, +> build on the existing patterns below; do not introduce parallel +> conventions. + ## Repository overview Helix is a monorepo containing a backend API and a frontend SPA: @@ -82,6 +89,12 @@ pnpm lint # ESLint ## General guidelines +- **Custom development.** When extending the boilerplate, use the existing + extension points rather than parallel patterns: add Flyway migrations for + schema changes, register message keys in every i18n bundle, implement features + through the standard `Controller → Service → Manager → Repository` chain, and + expose typed API clients in `web/src/api`. Customise the baseline — do not + re-architect it. - **Commits.** Use Conventional Commits (`feat:`, `fix:`, `refactor:`, `chore:`, `docs:`, `perf:`, `style:`, `test:`). Match the language of the surrounding history (the log is a mix of English and Chinese). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a467abe..7a03892 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,21 @@ # Contributing to Helix -Thanks for your interest in contributing! Helix is open source under the -[MIT licence](LICENCE). This guide explains how to set up your environment, -make changes and get them merged. +Thanks for your interest in contributing! Helix is a quick-start boilerplate for +custom development, open source under the [MIT licence](LICENCE). This guide +explains how to set up your environment, make changes and get them merged. + +## What to contribute + +Contributions should make the **boilerplate itself** more useful to everyone who +forks it: + +- New or improved baseline capabilities (reusable, not business-specific) +- Bug fixes and hardening +- Documentation and tests + +Changes that encode one particular organisation's custom rules are usually +better kept in your own fork. If you are not sure whether something belongs in +the boilerplate, open an issue first and ask. ## Getting started diff --git a/README.md b/README.md index f18744f..4cb1ee8 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,26 @@ # Helix -Helix is a self-hosted identity and access management (IAM) and organisation -administration platform built by [OnixByte](https://onixbyte.com). It manages -users, roles, departments, positions and navigation menus behind a single -sign-on experience, with support for Microsoft Entra ID (Azure AD), WeCom -(WeChat Work) and multi-factor authentication. +Helix is a **quick-start boilerplate** for building custom identity and organisation +management systems. It ships with a working full-stack baseline — authentication, +role-based access control, and user/role/department/position/menu management — so +you can start from a runnable application and customise it to your own +requirements instead of starting from zero. -The project is organised as a monorepo: +The boilerplate is organised as a monorepo: - **`server/`** — Spring Boot 3 REST API (Java 21, PostgreSQL, Redis, Flyway) - **`web/`** — React 19 single-page application (Vite, Ant Design, Tailwind CSS, Redux Toolkit) - **`docker/`** — deployment support files used by Docker Compose -## Features +> Helix is a starting point, not a finished product. Every baseline module is +> meant to be extended or replaced as part of your custom development. + +## Baseline capabilities + +Out of the box the boilerplate provides: - **Authentication & single sign-on** — username/password login with captcha, - Microsoft Entra ID (MSAL) sign-in, WeCom login and MFA + Microsoft Entra ID (MSAL) sign-in, WeCom (WeChat Work) login and MFA - **User management** — create, edit and deactivate users; assign roles, departments and positions - **Role-based access control** — roles with fine-grained authorities, enforced across all endpoints - **Organisation management** — departments, positions and custom navigation menus @@ -63,6 +68,21 @@ The project is organised as a monorepo: └── .env.example # Compose environment template ``` +## Customising the boilerplate + +Helix is designed to be forked and extended. The recommended approach: + +1. **Fork (or copy) the repository** and rename the project to your own. +2. **Change the branding** — application title (`VITE_APP_TITLE`), regions + (`VITE_DEFAULT_REGION_ABBREVIATION`), JWT issuer, S3 buckets and so on. +3. **Build on the baseline modules.** The existing patterns — custom validation + framework, `BizException` + `MessageName` error handling, JWT authentication, + Redux slices and typed API clients — are the extension points for your own + features. Follow the conventions in [AGENTS.md](AGENTS.md). +4. **Add schema changes as Flyway migrations** under + `server/src/main/resources/db/migrations/` and add new message keys to + **all** i18n bundles. + ## Quick start ### Full stack with Docker Compose @@ -151,6 +171,6 @@ it, set `app.asset.enabled: true` there and provide the `S3_*` variables. - Database schema is managed with Flyway — add migrations under `server/src/main/resources/db/migrations/` rather than relying on JPA `ddl-auto`. -## License +## Licence [MIT](LICENCE) © OnixByte