@clubedge/create-clubedge-app 0.2.0 → 0.3.0

package/template/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!) The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/template/NOTICE

@@ -0,0 +1,6 @@
+Clubedge Starter
+Copyright 2026 Clubedge Digital Systems
+
+This project is licensed under the Apache License, Version 2.0.
+The license text is available in the LICENSE file and at
+https://www.apache.org/licenses/LICENSE-2.0.

package/template/PUBLISHING.md

@@ -0,0 +1,27 @@
+# GitHub launch checklist
+
+This checklist is for repository maintainers preparing `clubedge-starter` for public use. The code changes alone cannot change GitHub repository visibility or security settings.
+
+## Before changing visibility
+
+- [ ] Review the [README](README.md), [setup guide](SETUP.md), [Apache-2.0 license](LICENSE), and [NOTICE](NOTICE).
+- [ ] Confirm `.env.local`, provider credentials, database dumps, and generated build output are not tracked. Only placeholder values belong in `.env.example`.
+- [ ] Search the full Git history for credentials before making the repository public. Rotating a leaked credential does not remove it from history.
+- [ ] Confirm the existing CI workflow passes on GitHub Actions for `main` and a pull request.
+- [ ] Set a concise repository description and useful topics such as `nextjs`, `shadcn-ui`, `pnpm`, `drizzle-orm`, `supabase`, and `starter-kit`.
+
+## Recommended GitHub settings
+
+- [ ] Change repository visibility to **Public** when the owner is ready to publish it.
+- [ ] Enable private vulnerability reporting under **Settings → Security** so the SECURITY.md reporting link works.
+- [ ] Protect `main` with pull requests and require the CI workflow to pass before merging.
+- [ ] Keep repository permissions least-privileged and grant write access only to trusted maintainers.
+- [ ] Decide whether to enable Discussions for support and design proposals; current support instructions use issues and pull requests.
+- [ ] Add maintainers to `CODEOWNERS` only if review requests should be assigned automatically.
+
+## After publication
+
+- [ ] Open the public README and setup links while signed out to confirm they are accessible.
+- [ ] Verify the Actions badge and issue forms render correctly.
+- [ ] Confirm the private vulnerability reporting path is available and points to the right repository.
+- [ ] Announce the project with a clear note that it is a community starter and that adopters must review deployment security and provider policies.

package/template/README.md

@@ -0,0 +1,157 @@
+# Clubedge Starter
+
+[![CI](https://github.com/Clubedge/clubedge-starter/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Clubedge/clubedge-starter/actions/workflows/ci.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
+
+Clubedge Starter is a production-oriented, modular Next.js application foundation. It brings together a pnpm monorepo, shared shadcn/ui components, PostgreSQL access through Drizzle, Supabase Auth, optional Redis and storage adapters, and a working example dashboard. It provides engineering conventions and a reference implementation; review its security and deployment choices for your application before production use.
+
+This is a starter, not a hosted service or a one-command app generator. Fork it or use it as a reference, then adapt the app and provider configuration to your project. Contributions and bug reports are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). Repository maintainers can use [PUBLISHING.md](PUBLISHING.md) for the GitHub launch checklist.
+
+## Features
+
+- Next.js App Router, React, TypeScript, Tailwind CSS 4, and shadcn/ui using Base UI primitives.
+- pnpm workspaces and Turborepo, with the web app in `apps/web` and reusable UI source in `packages/ui`.
+- Drizzle ORM and PostgreSQL schema, migrations, and seed commands.
+- Supabase Auth using cookie based server clients from `@supabase/ssr`.
+- S3 compatible storage (including Cloudflare R2) and Supabase Storage adapters.
+- Optional Redis cache and fixed-window rate limiter using a standard Redis URL.
+- Zod environment validation, security headers, structured errors, and `/api/health`.
+- Docker support, GitHub Actions CI, Vitest, Playwright, ESLint, and Prettier.
+
+## Stack and provider choices
+
+| Capability              | Included choice                                      | Other supported options                                               |
+| ----------------------- | ---------------------------------------------------- | --------------------------------------------------------------------- |
+| Web app                 | Next.js App Router, React, TypeScript                | —                                                                     |
+| UI                      | Tailwind CSS 4, shadcn/ui, and Base UI               | Add or replace components in your app or shared UI package.           |
+| Database                | PostgreSQL through Drizzle ORM                       | Any reachable PostgreSQL provider; Supabase PostgreSQL is documented. |
+| Authentication          | Supabase Auth with `@supabase/ssr`                   | No alternate auth adapter is currently included.                      |
+| Cache and rate limiting | Optional Redis protocol client                       | Upstash, self-hosted Redis, or a compatible Redis service.            |
+| Object storage          | S3-compatible adapter or Supabase Storage            | AWS S3, Cloudflare R2, and other S3-compatible services.              |
+| Local runtime           | Docker and Next.js standalone output                 | Run directly with Node.js during development.                         |
+| Verification            | Vitest, Playwright, ESLint, Prettier, GitHub Actions | —                                                                     |
+
+## Architecture
+
+```mermaid
+flowchart TB
+  Browser --> Next[Next.js application]
+  Next -->|auth interface and server sessions| Auth[Supabase Auth]
+  Next -->|Drizzle ORM| DB[(PostgreSQL)]
+  Next -->|optional cache and rate limits| Redis[(Redis)]
+  Next -->|storage interface| Storage{Storage provider}
+  Storage --> S3[S3-compatible storage: AWS S3, R2, MinIO]
+  Storage --> SupabaseStorage[Supabase Storage]
+```
+
+Drizzle manages application data in PostgreSQL. Supabase Auth manages identity and sessions separately; it is not accessed through Drizzle. The PostgreSQL database may be Supabase PostgreSQL or another PostgreSQL provider.
+
+### Architecture principles
+
+- **PostgreSQL is the source of truth for application data.** Drizzle centralizes application schema, queries, and migrations.
+- **Authentication stays separate from application data.** Supabase Auth owns credentials and sessions; application tables are managed by Drizzle.
+- **Infrastructure dependencies stay optional where practical.** Redis is only needed for distributed cache and rate limiting. Without Redis, the rate limiter falls back to a per-process memory window, which is suitable for a single server instance only.
+- **Storage has a provider boundary.** Application code can use the storage interface with S3-compatible services or Supabase Storage; authorization and upload validation remain the caller's responsibility.
+- **Shared packages are framework-agnostic.** Packages under `packages/` receive configuration and request cookies as arguments and never import Next.js, so another app (for example a TanStack Start app) can reuse them unchanged. ESLint enforces these boundaries.
+- **One composition root per app.** `apps/web/src/server/` is the only place that reads environment variables and chooses providers. Routes, actions, and components call it rather than a provider SDK.
+- **Keep the baseline focused.** Additional providers, queues, and generator tooling should be added when a real use case calls for them.
+
+## Quick start
+
+### Requirements
+
+- Node.js 22.12 or newer (Node.js 22 LTS recommended).
+- pnpm 10.9.0. The repository pins its package manager version using Corepack.
+- PostgreSQL when using database features. A Supabase project can provide both PostgreSQL and Auth.
+
+### Install and run
+
+```sh
+corepack enable
+pnpm install
+```
+
+Copy the example environment file to the web app's local environment file.
+
+PowerShell:
+
+```powershell
+Copy-Item .env.example apps/web/.env.local
+```
+
+macOS/Linux:
+
+```sh
+cp .env.example apps/web/.env.local
+```
+
+Set `DATABASE_URL` in `apps/web/.env.local`. Supabase Auth is optional for exploring the UI; set `NEXT_PUBLIC_SUPABASE_URL` and `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` to enable it. See [SETUP.md](SETUP.md) for provider setup and optional integrations. Then start the app:
+
+```sh
+pnpm dev
+```
+
+Open <http://localhost:3000> for the landing page, <http://localhost:3000/dashboard> for the starter dashboard, or <http://localhost:3000/api/health> for the liveness endpoint. The pages render without connecting to providers. Database, authentication, storage, and Redis operations require their respective configuration.
+
+## Common commands
+
+Run these from the repository root:
+
+| Command             | Purpose                                        |
+| ------------------- | ---------------------------------------------- |
+| `pnpm dev`          | Start the web app in development mode.         |
+| `pnpm build`        | Create a production build.                     |
+| `pnpm start`        | Start the standalone production build.         |
+| `pnpm lint`         | Run ESLint.                                    |
+| `pnpm typecheck`    | Typecheck the workspaces.                      |
+| `pnpm test`         | Run Vitest.                                    |
+| `pnpm test:e2e`     | Run Playwright browser checks.                 |
+| `pnpm format`       | Format supported repository files.             |
+| `pnpm format:check` | Check formatting without writing files.        |
+| `pnpm db:generate`  | Generate Drizzle migrations from the schema.   |
+| `pnpm db:migrate`   | Apply checked-in Drizzle migrations.           |
+| `pnpm db:push`      | Push schema directly (local development only). |
+| `pnpm db:studio`    | Open Drizzle Studio.                           |
+| `pnpm db:check`     | Check migration consistency.                   |
+| `pnpm db:seed`      | Seed the configured database.                  |
+
+Playwright's first run may require installing Chromium with `pnpm exec playwright install chromium`. CI runs the browser checks automatically.
+
+## Repository structure
+
+```text
+apps/web/            Next.js app: routes, actions, UI, and the composition root
+  src/server/        Wires environment, cookies, and providers into the packages
+packages/core/       Errors, Result type, and HTTP helpers (no dependencies)
+packages/auth/       AuthProvider and CookieStore interfaces, Supabase adapter
+packages/db/         Drizzle schema, client factory, migrations, and seed script
+packages/storage/    StorageProvider interface, S3 and Supabase Storage adapters
+packages/cache/      Rate limiters (memory and Redis) and Redis cache
+packages/ui/         Shared shadcn/ui components, utilities, and global theme styles
+.github/             CI workflow, issue forms, and pull request template
+SETUP.md        Detailed local and provider setup
+CONTRIBUTING.md Contribution workflow and review expectations
+SECURITY.md     Vulnerability reporting guidance
+```
+
+The project name, description, service identifier, and documentation links live in `apps/web/src/config/site.json`. Edit that file to rename the app; `create-clubedge-app` writes it for generated projects.
+
+## Shared UI components
+
+The shared component package is `@clubedge/ui`. It uses the shadcn `base-nova` style, which generates components backed by `@base-ui/react` rather than Radix UI. The landing page and dashboard demonstrate the shared sidebar, breadcrumbs, theme switch, buttons, cards, badges, separators, inputs, labels, and tables. The light/dark theme preference is stored in the browser; dark mode uses a `#151515` page background and blue `#2563eb` primary color.
+
+Add a component from the repository root using the web app's config:
+
+```sh
+pnpm dlx shadcn@latest add badge -c apps/web
+```
+
+Shared components are generated under `packages/ui/src/components` and can be imported from `@clubedge/ui/components/<component>`. The two `components.json` files intentionally share the `base-nova` style, neutral color base, Lucide icons, Tailwind v4 stylesheet, and RTL-aware generation setting. The app currently renders English in LTR; set the root document's `lang` and `dir` for the locale used by your application. Put app-only components in `apps/web/src/components`.
+
+## Contributing
+
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue or pull request. For local changes, run the relevant checks before submitting. You can report vulnerabilities privately using the process in [SECURITY.md](SECURITY.md).
+
+## License
+
+Copyright © 2026 Clubedge Digital Systems. This project is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/template/SECURITY.md

@@ -0,0 +1,15 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are made against the latest code on the `main` branch. This starter does not currently publish versioned releases or promise a support window for forks.
+
+## Report a vulnerability
+
+Please do not report exploitable vulnerabilities in a public issue or pull request. Use GitHub's **Report a vulnerability** option in the repository's Security tab to send a private report. If private vulnerability reporting is unavailable, contact the repository owner through [their GitHub profile](https://github.com/Clubedge) and include enough detail to reproduce the issue safely.
+
+Include the affected component or file, impact, reproduction steps or proof of concept, and any suggested mitigation. Please allow reasonable time for investigation and a fix before sharing details publicly. We will acknowledge reports and coordinate next steps through GitHub.
+
+## Secret exposure
+
+If a credential was committed or exposed, revoke or rotate it with its provider immediately. Removing it from the latest commit does not invalidate it or remove it from Git history. Report the incident privately as described above.

package/template/SETUP.md

@@ -0,0 +1,174 @@
+# Setup guide
+
+This guide covers local development and provider setup for Clubedge Starter. Start with the [README](README.md) for the architecture overview, then follow only the provider sections your project needs.
+
+## 1. Install the toolchain
+
+Install Node.js 22.12 or newer, then enable Corepack and install pnpm dependencies from the repository root:
+
+```sh
+corepack enable
+pnpm install
+```
+
+The root `package.json` pins pnpm 10.9.0 through its `packageManager` field. Use a compatible pnpm 10 release if Corepack is not available.
+
+If pnpm reports that it ignored a package build script needed by your environment, review the package name and approve only the required dependency with `pnpm approve-builds`.
+
+## 2. Configure local environment
+
+Copy `.env.example` to `apps/web/.env.local`.
+
+PowerShell:
+
+```powershell
+Copy-Item .env.example apps/web/.env.local
+```
+
+macOS/Linux:
+
+```sh
+cp .env.example apps/web/.env.local
+```
+
+The example file leaves optional provider URLs and keys blank so the app can build and start without connecting to real services. At minimum, set `DATABASE_URL`; set the Supabase values when you want to use authentication.
+
+Edit these values as needed:
+
+| Variable                               | Required          | Description                                                                                        |
+| -------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------- |
+| `DATABASE_URL`                         | Yes               | PostgreSQL connection URL. Use a Supabase transaction pooler URL or another PostgreSQL connection. |
+| `NEXT_PUBLIC_SUPABASE_URL`             | For Supabase Auth | Project URL, such as `https://<project-ref>.supabase.co`.                                          |
+| `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` | For Supabase Auth | Supabase publishable key. This key is intended for the browser; never use a service role key here. |
+| `NEXT_PUBLIC_APP_URL`                  | Recommended       | The app's origin, defaulting to `http://localhost:3000`.                                           |
+
+`DATABASE_URL` must be a non-empty string for server environment validation. If you are only exploring the UI, you can use a local placeholder URL, but database operations will fail until it points to a real PostgreSQL database.
+
+Start the development server:
+
+```sh
+pnpm dev
+```
+
+The app is available at <http://localhost:3000> and the liveness endpoint at <http://localhost:3000/api/health>.
+
+## 3. Configure Supabase Auth
+
+Create or select a Supabase project. Set `NEXT_PUBLIC_SUPABASE_URL` and `NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY` from the project's API settings. For the database, use the transaction pooler URL when appropriate; the Postgres.js client is configured with `prepare: false` for compatibility with Supabase transaction pooling.
+
+In Supabase Auth URL configuration, add this redirect URL for local email confirmation:
+
+```text
+http://localhost:3000/auth/callback
+```
+
+For deployed environments, add the corresponding `${NEXT_PUBLIC_APP_URL}/auth/callback` URL. The app uses the publishable key and validates users through its server auth adapter. Never expose a Supabase service role key to the client.
+
+## 4. Set up the database
+
+Application tables are managed with Drizzle. Supabase Auth manages its own auth tables. Keep one migration source of truth for application tables: do not also create an independent Supabase migration history for those same tables.
+
+From the repository root:
+
+```sh
+pnpm db:check
+pnpm db:generate
+pnpm db:migrate
+```
+
+`db:generate` creates migration files from `packages/db/src/schema` into `packages/db/drizzle`; review and commit those files. `db:migrate` applies committed migrations. `db:push` is available for local development, but do not use it as a production migration workflow. Use `pnpm db:seed` only against a database where seed data is appropriate. The database commands run in `packages/db` and read `DATABASE_URL` from `apps/web/.env.local`, so the project keeps one environment file.
+
+## 5. Configure optional services
+
+### Redis
+
+Redis is optional. Set `REDIS_URL` to a TCP connection URL:
+
+```dotenv
+REDIS_URL=rediss://default:<password>@<host>:6379
+```
+
+Use `rediss://` for TLS connections such as Upstash and `redis://` for an unencrypted connection on a trusted network. Self-hosted Redis can use either scheme according to its TLS configuration. The app uses the standard Redis protocol and requires a Node.js runtime with outbound TCP access; this adapter is not for Edge runtimes that cannot open TCP connections.
+
+When Redis is not configured, cache reads return a miss and `createRateLimiter()` falls back to an in-memory fixed window. Memory limits apply per server process, so configure Redis when you run several instances or serverless functions. Sign-in and sign-up attempts are limited to ten per minute per client address. Never commit a real Redis URL or password.
+
+### Object storage
+
+Set `STORAGE_PROVIDER=s3` for AWS S3 or an S3-compatible provider such as Cloudflare R2. Configure `STORAGE_BUCKET`, `STORAGE_REGION`, `STORAGE_ENDPOINT` when required, and the access key, secret, and optional public URL. For R2, use the account's S3 API endpoint and region `auto`.
+
+Set `STORAGE_PROVIDER=supabase` to select the Supabase Storage adapter and configure `SUPABASE_STORAGE_BUCKET`. This adapter uses the configured Supabase server client. Choose a bucket policy that matches your application's access model.
+
+The storage adapter does not authorize users or validate uploads. Before calling it, the route or action must check ownership and authorization, file size, content type, and the object key. Keep credentials server side.
+
+## 6. Shared UI development
+
+The repo uses matching `apps/web/components.json` and `packages/ui/components.json` files to direct the shadcn CLI into the shared `packages/ui` package. The selected `base-nova` style uses `@base-ui/react` primitives, not Radix UI. Tailwind CSS 4 and semantic theme tokens are defined in `packages/ui/src/styles/globals.css` and imported by the web app's root layout.
+
+Generate a shared component from the repository root:
+
+```sh
+pnpm dlx shadcn@latest add badge -c apps/web
+```
+
+Shared components live in `packages/ui/src/components` and are imported from `@clubedge/ui/components/<component>`. Keep both `components.json` files aligned when changing the shadcn style, Tailwind CSS entry, base color, icon library, or RTL setting. The `rtl` setting makes newly generated components RTL-aware; set `lang` and `dir` on the root `<html>` element to match your application's actual locale. App-specific components belong in `apps/web/src/components`.
+
+The root route is a public landing page; the reference dashboard is available at `/dashboard`. The dashboard uses the shared shadcn sidebar and breadcrumb. A light/dark switch is available in the landing page and dashboard navigation; its choice is saved in local storage and the initial theme follows the system preference until the user selects one. Theme colors are centralized in `packages/ui/src/styles/globals.css` (blue `#2563eb`, dark background `#151515`).
+
+## 7. Docker
+
+Create `apps/web/.env.local` first. Start the development image with:
+
+```sh
+pnpm docker:dev
+```
+
+Build a production image and run it with:
+
+```sh
+pnpm docker:build
+pnpm docker:start
+```
+
+The Docker image uses Next.js standalone output and runs as an unprivileged user. Ensure the configured database and provider hosts are reachable from the container.
+
+## 8. Checks
+
+Run the checks relevant to your change before opening a pull request:
+
+```sh
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm format:check
+pnpm build
+```
+
+Browser checks use Playwright. Install Chromium once, then run `pnpm test:e2e`:
+
+```sh
+pnpm exec playwright install chromium
+pnpm test:e2e
+```
+
+The Playwright configuration starts the local app with a placeholder database URL; browser scenarios should not require real provider credentials.
+
+## Before deploying
+
+This repository is a starting point; review the security and operational choices for your application before production use:
+
+- Set production environment variables through your hosting provider's secret manager. Use unique, rotated credentials and TLS for external connections.
+- Set `NEXT_PUBLIC_APP_URL` to the deployed origin and add its `/auth/callback` URL to Supabase's allowed redirect URLs.
+- Make authenticated server routes call `getCurrentUser()` or `requireUser()` from `@/server/auth` (the latter throws a 401 `AppError`), and protect pages with `getPageUser(pathname)`, which redirects signed-out visitors to `/login`. Do not treat cookie contents alone as proof of identity.
+- Authorize storage access and validate upload size, content type, and object ownership in the route or action before using the storage adapter.
+- Configure Redis for rate limiting when you deploy more than one instance; the in-memory fallback does not share counts between instances. Client addresses come from `x-forwarded-for`, so deploy behind a proxy that sets it.
+- Configure and verify a restrictive Content Security Policy for the scripts and asset origins used by your deployment. A generic policy is not included because it can break framework tooling and project-specific assets.
+- Review database migration and backup procedures, provider access policies, and application-specific error handling.
+
+## Troubleshooting
+
+- **Environment validation fails:** confirm you copied the example to `apps/web/.env.local` and set `DATABASE_URL`.
+- **Auth redirects fail:** add the exact local or deployed `/auth/callback` URL to Supabase Auth's allowed redirect URLs.
+- **Database connection fails:** check the URL, network access, and whether your provider expects a transaction pooler. Keep `prepare: false` for the current Supabase pooler setup.
+- **Redis cannot connect:** check that the URL uses `redis://` or `rediss://`, credentials are current, and outbound TCP access is allowed.
+- **Playwright cannot find Chromium:** run `pnpm exec playwright install chromium`.
+- **A package file appears missing after an offline install:** retry with a normal registry-backed `pnpm install`; an incomplete local package cache can satisfy offline resolution while leaving package contents incomplete.

package/template/SUPPORT.md

@@ -0,0 +1,8 @@
+# Getting help
+
+- For installation and provider configuration, start with [SETUP.md](SETUP.md).
+- For defects, search existing issues and then open a bug report using the repository issue form.
+- For improvements, open a feature request or a discussion issue describing the use case before starting a large change.
+- For security vulnerabilities, use the private process in [SECURITY.md](SECURITY.md); do not post exploit details publicly.
+
+This is a community-maintained starter project. It does not currently offer paid support or response-time guarantees.

package/template/_gitignore

@@ -0,0 +1,13 @@
+node_modules/
+.pnpm-store/
+.turbo/
+.next/
+out/
+build/
+coverage/
+playwright-report/
+test-results/
+.env*
+!.env.example
+!.env.test.example
+*.tsbuildinfo

package/template/apps/web/AGENTS.md

@@ -0,0 +1,9 @@
+<!-- BEGIN:nextjs-agent-rules -->
+
+## This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+
+<!-- END:nextjs-agent-rules -->

package/template/apps/web/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-nova",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "../../packages/ui/src/styles/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@clubedge/ui/lib/utils",
+    "ui": "@clubedge/ui/components",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide",
+  "rtl": true
+}