Skip to content

Commit fbd6f82

Browse files
JCFcodexJCFcodex
committed
docs: overhaul README with deployment guides, feature lists, and improved structure
1 parent 3db7c16 commit fbd6f82

1 file changed

Lines changed: 161 additions & 96 deletions

File tree

‎README.md‎

Lines changed: 161 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -5,61 +5,103 @@
55
</div>
66

77
<p align="center">
8-
<strong>Launch production-ready SaaS applications in days, not months.</strong><br/>
9-
<em>A modern Next.js 16 architecture integrating authentication, billing, CMS, email, and a polished UI system.</em>
8+
<strong>Launch production-ready SaaS applications in days, not months.</strong><br />
9+
<em>A modern Next.js 16 starter kit with authentication, billing, CMS, email, and a polished UI system — all wired together.</em>
1010
</p>
1111

1212
<p align="center">
13-
<a href="https://github.com/JCFcodex/AinzStack/actions"><img src="https://img.shields.io/badge/build-passing-success?style=flat-square" alt="Build" /></a>
14-
<a href="#"><img src="https://img.shields.io/badge/version-0.1.0-blue?style=flat-square" alt="Version" /></a>
15-
<a href="#"><img src="https://img.shields.io/badge/Next.js-16.1.6-black?style=flat-square&logo=next.js" alt="Next.js" /></a>
16-
<a href="#"><img src="https://img.shields.io/badge/React-19.2.4-149eca?style=flat-square&logo=react" alt="React" /></a>
17-
<a href="#"><img src="https://img.shields.io/badge/TypeScript-Strict-3178c6?style=flat-square&logo=typescript" alt="TypeScript" /></a>
18-
<a href="#"><img src="https://img.shields.io/badge/Tailwind_CSS-v4-38bdf8?style=flat-square&logo=tailwindcss" alt="Tailwind" /></a>
19-
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License" /></a>
13+
<a href="https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FJCFcodex%2FAinzStack&env=NEXT_PUBLIC_APP_URL,NEXT_PUBLIC_SUPABASE_URL,NEXT_PUBLIC_SUPABASE_ANON_KEY,SUPABASE_SERVICE_ROLE_KEY,NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,STRIPE_SECRET_KEY,STRIPE_WEBHOOK_SECRET,SANITY_PROJECT_ID,SANITY_DATASET,RESEND_API_KEY&project-name=ainzstack&repository-name=ainzstack"><img src="https://vercel.com/button" alt="Deploy with Vercel" height="32" /></a>
14+
&nbsp;&nbsp;
15+
<a href="https://render.com/deploy?repo=https://github.com/JCFcodex/AinzStack"><img src="https://render.com/images/deploy-to-render-button.svg" alt="Deploy to Render" height="32" /></a>
16+
</p>
17+
18+
<p align="center">
19+
<a href="https://github.com/JCFcodex/AinzStack/actions"><img src="https://img.shields.io/badge/build-passing-success?style=flat-square" alt="Build Status" /></a>
20+
<a href="https://github.com/JCFcodex/AinzStack/releases"><img src="https://img.shields.io/badge/version-0.1.0-blue?style=flat-square" alt="Version" /></a>
21+
<a href="https://nextjs.org/"><img src="https://img.shields.io/badge/Next.js-16.1.6-black?style=flat-square&logo=next.js" alt="Next.js" /></a>
22+
<a href="https://react.dev/"><img src="https://img.shields.io/badge/React-19.2.4-149eca?style=flat-square&logo=react" alt="React" /></a>
23+
<a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-Strict-3178c6?style=flat-square&logo=typescript" alt="TypeScript" /></a>
24+
<a href="https://tailwindcss.com/"><img src="https://img.shields.io/badge/Tailwind_CSS-v4-38bdf8?style=flat-square&logo=tailwindcss" alt="Tailwind CSS" /></a>
25+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT License" /></a>
2026
</p>
2127

2228
---
2329

24-
## Overview
30+
## Table of Contents
31+
32+
- [Table of Contents](#table-of-contents)
33+
- [Overview](#overview)
34+
- [Features](#features)
35+
- [Tech Stack](#tech-stack)
36+
- [Getting Started](#getting-started)
37+
- [Prerequisites](#prerequisites)
38+
- [Installation](#installation)
39+
- [Environment Variables](#environment-variables)
40+
- [Running Locally](#running-locally)
41+
- [Project Structure](#project-structure)
42+
- [Available Scripts](#available-scripts)
43+
- [Deployment](#deployment)
44+
- [Deploy to Vercel](#deploy-to-vercel)
45+
- [Deploy to Render](#deploy-to-render)
46+
- [Post-Deployment Checklist](#post-deployment-checklist)
47+
- [License](#license)
2548

26-
AinzStack provides the foundational momentum required to ship robust software. By abstracting away the boilerplate integration of core SaaS primitives, it allows engineering teams to focus immediately on product logic.
49+
---
2750

28-
Auth flows are integrated via Supabase. Billing is wired through Stripe. Marketing and dashboard layouts are production-scaffolded. Sanity and Resend form the content and communication layers. CI/CD, typing, and testing are structurally enforced.
51+
## Overview
2952

30-
### Interface
53+
AinzStack is a full-stack SaaS starter kit that handles the repetitive integration work so you can focus on building product. Authentication, billing, content management, transactional email, marketing pages, and a dashboard — all pre-wired and production-scaffolded.
3154

3255
<p align="center">
3356
<img src="public/preview.png" alt="AinzStack Preview" width="100%" />
3457
</p>
3558

3659
---
3760

38-
## Technical Foundation
39-
40-
| Layer | Implementation |
41-
| :------------------ | :--------------------------------------------------- |
42-
| **Framework** | Next.js App Router, Turbopack, React 19 |
43-
| **Authentication** | Supabase (Email/Password, Google OAuth), SSR handled |
44-
| **Database** | Supabase PostgreSQL |
45-
| **Payments** | Stripe Checkout, integrated Webhook routing |
46-
| **Content** | Sanity CMS client and schema foundation |
47-
| **Email** | Resend API integration |
48-
| **Styling** | Tailwind CSS v4, Framer Motion primitives |
49-
| **State** | React Query, Zustand |
50-
| **Validation** | Zod, React Hook Form |
51-
| **Quality Control** | TypeScript (Strict), ESLint, Vitest, Playwright |
61+
## Features
62+
63+
- **Authentication** — Email/password and Google OAuth via Supabase, with SSR session handling
64+
- **Billing** — Stripe Checkout integration with webhook routing for subscription lifecycle events
65+
- **Content Management** — Sanity CMS client and schema foundation for structured content
66+
- **Transactional Email** — Resend API integration for notifications and onboarding flows
67+
- **Marketing Site** — Pre-built public-facing pages and layout scaffolding
68+
- **Dashboard** — Secured application interface with sidebar navigation
69+
- **UI System** — Tailwind CSS v4 with Framer Motion animation primitives
70+
- **Form Handling** — Zod schema validation paired with React Hook Form
71+
- **State Management** — React Query for server state, Zustand for client state
72+
- **Quality Enforcement** — Strict TypeScript, ESLint, Vitest unit tests, and Playwright E2E tests
73+
- **CI-Ready** — Single `pnpm ci` command runs the full lint → typecheck → test → build pipeline
74+
75+
---
76+
77+
## Tech Stack
78+
79+
| Layer | Technology |
80+
| :----------------- | :--------------------------------------------------- |
81+
| **Framework** | Next.js App Router, Turbopack, React 19 |
82+
| **Authentication** | Supabase (Email/Password, Google OAuth), SSR handled |
83+
| **Database** | Supabase PostgreSQL |
84+
| **Payments** | Stripe Checkout, Webhook routing |
85+
| **Content** | Sanity CMS |
86+
| **Email** | Resend |
87+
| **Styling** | Tailwind CSS v4, Framer Motion |
88+
| **State** | React Query, Zustand |
89+
| **Validation** | Zod, React Hook Form |
90+
| **Testing** | Vitest (unit), Playwright (E2E) |
91+
| **Tooling** | TypeScript (strict), ESLint, pnpm |
5292

5393
---
5494

5595
## Getting Started
5696

5797
### Prerequisites
5898

59-
- Node.js `v22.0.0` or higher
60-
- pnpm `v10.0.0` or higher
99+
| Tool | Minimum Version |
100+
| :------ | :-------------- |
101+
| Node.js | `v22.0.0` |
102+
| pnpm | `v10.0.0` |
61103

62-
### Initialization
104+
### Installation
63105

64106
Clone the repository and install dependencies:
65107

@@ -69,113 +111,136 @@ cd AinzStack
69111
pnpm install
70112
```
71113

72-
### Environment Configuration
114+
### Environment Variables
73115

74-
Duplicate the environment template:
116+
Copy the example environment file and fill in your credentials:
75117

76118
```bash
77119
cp .env.example .env.local
78120
```
79121

80-
Populate `.env.local` with your distinct credentials. Essential variables include:
81-
82-
```env
83-
NEXT_PUBLIC_APP_URL=
84-
NEXT_PUBLIC_SUPABASE_URL=
85-
NEXT_PUBLIC_SUPABASE_ANON_KEY=
86-
SUPABASE_SERVICE_ROLE_KEY=
87-
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
88-
STRIPE_SECRET_KEY=
89-
STRIPE_WEBHOOK_SECRET=
90-
SANITY_PROJECT_ID=
91-
SANITY_DATASET=
92-
RESEND_API_KEY=
93-
```
122+
The following variables are required in `.env.local`:
123+
124+
| Variable | Description |
125+
| :----------------------------------- | :------------------------------------------- |
126+
| `NEXT_PUBLIC_APP_URL` | Your application's base URL |
127+
| `NEXT_PUBLIC_SUPABASE_URL` | Supabase project URL |
128+
| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Supabase anonymous (public) key |
129+
| `SUPABASE_SERVICE_ROLE_KEY` | Supabase service role key (server-side only) |
130+
| `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Stripe publishable key |
131+
| `STRIPE_SECRET_KEY` | Stripe secret key (server-side only) |
132+
| `STRIPE_WEBHOOK_SECRET` | Stripe webhook signing secret |
133+
| `SANITY_PROJECT_ID` | Sanity project ID |
134+
| `SANITY_DATASET` | Sanity dataset name (e.g., `production`) |
135+
| `RESEND_API_KEY` | Resend API key for transactional email |
94136

95-
### Development Server
137+
> **Note:** Variables prefixed with `NEXT_PUBLIC_` are exposed to the browser. Never prefix secret keys with `NEXT_PUBLIC_`.
96138
97-
Initiate the local environment:
139+
### Running Locally
140+
141+
Start the development server:
98142

99143
```bash
100144
pnpm dev
101145
```
102146

103-
The application will be available at `http://localhost:3000`.
147+
Open [http://localhost:3000](http://localhost:3000) in your browser.
104148

105149
---
106150

107-
## Architecture
108-
109-
The project enforces a strict, scalable directory structure:
151+
## Project Structure
110152

111153
```text
112154
src/
113155
├── app/
114-
│ ├── (auth)/ # Authentication flows
156+
│ ├── (auth)/ # Authentication flows (login, signup, callback)
115157
│ ├── (dashboard)/ # Secured application interface
116-
│ ├── (marketing)/ # Public-facing routes
117-
│ └── api/ # Edge and Node.js route handlers
118-
├── actions/ # Server Actions for data mutation
158+
│ ├── (marketing)/ # Public-facing marketing pages
159+
│ └── api/ # API route handlers (Edge & Node.js)
160+
├── actions/ # Server Actions for data mutations
119161
├── components/
120-
│ ├── layout/ # Structural components (nav, sidebar)
121-
│ ├── providers/ # Context and service providers
122-
│ └── ui/ # Reusable primitive components
123-
└── lib/ # Core integrations and utilities
124-
├── auth/
125-
├── sanity/
126-
├── stripe/
127-
└── supabase/
162+
│ ├── layout/ # Structural components (navbar, sidebar, footer)
163+
│ ├── providers/ # React context and service providers
164+
│ └── ui/ # Reusable UI primitives
165+
└── lib/ # Core integrations and shared utilities
166+
├── auth/ # Authentication helpers
167+
├── sanity/ # Sanity client and schemas
168+
├── stripe/ # Stripe client and webhook logic
169+
└── supabase/ # Supabase client configuration
128170
```
129171

130172
---
131173

132-
## Deployment Considerations
133-
134-
When transitioning to production environments, ensure the following constraints are met:
174+
## Available Scripts
135175

136-
1. **Absolute URLs:** Assign `NEXT_PUBLIC_APP_URL` to your authoritative production domain.
137-
2. **Authentication Callbacks:** Register your production callback URI within the Supabase dashboard (e.g., `https://[domain.com]/auth/callback`).
138-
3. **Webhooks:** Update your Stripe webhook endpoints to target your production deployment.
176+
| Command | Description |
177+
| :--------------- | :----------------------------------------------------- |
178+
| `pnpm dev` | Start the development server with Turbopack |
179+
| `pnpm build` | Create an optimized production build |
180+
| `pnpm start` | Serve the production build locally |
181+
| `pnpm lint` | Run ESLint static analysis |
182+
| `pnpm typecheck` | Run TypeScript type checking |
183+
| `pnpm test` | Run unit tests with Vitest |
184+
| `pnpm test:e2e` | Run end-to-end tests with Playwright |
185+
| `pnpm ci` | Run full CI pipeline (lint → typecheck → test → build) |
139186

140187
---
141188

142-
## Commands
189+
## Deployment
143190

144-
A comprehensive suite of scripts is provided for the development lifecycle:
191+
### Deploy to Vercel
145192

146-
| Command | Action |
147-
| :--------------- | :-------------------------------------------------- |
148-
| `pnpm dev` | Start the development server |
149-
| `pnpm build` | Compile the application for production |
150-
| `pnpm start` | Run the compiled production server |
151-
| `pnpm lint` | Execute static code analysis via ESLint |
152-
| `pnpm typecheck` | Validate TypeScript typings |
153-
| `pnpm test` | Run unit testing suite via Vitest |
154-
| `pnpm test:e2e` | Run end-to-end testing via Playwright |
155-
| `pnpm ci` | Run full CI workflow (Lint, Typecheck, Test, Build) |
193+
The fastest path to production. Click the button to clone the repo into your Vercel account, fill in your environment variables, and deploy — all in one step.
156194

157-
---
195+
<p align="center">
196+
<a href="https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FJCFcodex%2FAinzStack&env=NEXT_PUBLIC_APP_URL,NEXT_PUBLIC_SUPABASE_URL,NEXT_PUBLIC_SUPABASE_ANON_KEY,SUPABASE_SERVICE_ROLE_KEY,NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,STRIPE_SECRET_KEY,STRIPE_WEBHOOK_SECRET,SANITY_PROJECT_ID,SANITY_DATASET,RESEND_API_KEY&project-name=ainzstack&repository-name=ainzstack"><img src="https://vercel.com/button" alt="Deploy with Vercel" height="32" /></a>
197+
</p>
198+
199+
Vercel will prompt you to provide each required environment variable during setup. Refer to the [Environment Variables](#environment-variables) table for descriptions.
158200

159-
## Contributing
201+
### Deploy to Render
202+
203+
Prefer Render? Click the button below to create a new web service from this repository. Render will use the `render.yaml` blueprint in the repo to configure the service automatically.
204+
205+
<p align="center">
206+
<a href="https://render.com/deploy?repo=https://github.com/JCFcodex/AinzStack"><img src="https://render.com/images/deploy-to-render-button.svg" alt="Deploy to Render" height="32" /></a>
207+
</p>
160208

161-
We value engineering rigor and clear communication. To contribute:
209+
> **Render setup notes:**
210+
> - Add all required [environment variables](#environment-variables) in the Render dashboard under **Environment**.
211+
> - Set the **Build Command** to `pnpm build` and the **Start Command** to `pnpm start` (these are pre-configured in `render.yaml` if the blueprint file is present).
212+
> - Ensure the Node.js version is set to `22` or higher in your service settings.
162213
163-
1. Fork the repository.
164-
2. Checkout a scoped feature branch (`git checkout -b feature/module-name`).
165-
3. Commit your changes with descriptive messages.
166-
4. Execute the validation suite locally (`pnpm ci`).
167-
5. Open a Pull Request detailing your modifications.
214+
### Post-Deployment Checklist
215+
216+
Regardless of your hosting provider, verify the following after your first deploy:
217+
218+
1. **Base URL** — Set `NEXT_PUBLIC_APP_URL` to your production domain (e.g., `https://yourdomain.com`).
219+
2. **Auth Callbacks** — Register your production callback URI in the [Supabase Dashboard](https://supabase.com/dashboard) under **Authentication → URL Configuration**:
220+
```
221+
https://yourdomain.com/auth/callback
222+
```
223+
3. **Stripe Webhooks** — Update your [Stripe webhook endpoints](https://dashboard.stripe.com/webhooks) to point to your production URL:
224+
```
225+
https://yourdomain.com/api/stripe/webhook
226+
```
227+
228+
---
229+
230+
## License
231+
232+
This project is licensed under the [MIT License](LICENSE).
168233

169234
---
170235

171236
<div align="center">
172237
<p>
173-
<a href="https://github.com/JCFcodex/AinzStack">Repository</a> •
174-
<a href="https://github.com/JCFcodex/AinzStack/issues">Issue Tracker</a> •
175-
<a href="https://github.com/sponsors/JCFcodex">Sponsorship</a>
238+
<a href="https://github.com/JCFcodex/AinzStack">GitHub</a> ·
239+
<a href="https://github.com/JCFcodex/AinzStack/issues">Issues</a> ·
240+
<a href="https://github.com/JCFcodex/AinzStack/discussions">Discussions</a> ·
241+
<a href="https://github.com/sponsors/JCFcodex">Sponsor</a>
176242
</p>
177243
<p>
178-
<em>Built by <a href="https://github.com/JCFcodex">JCFcodex</a></em><br/>
179-
<small>Released under the <a href="LICENSE">MIT License</a></small>
244+
Built by <a href="https://github.com/JCFcodex">JCFcodex</a>
180245
</p>
181-
</div>
246+
</div>

0 commit comments

Comments
 (0)