Skip to content

Commit 23f964b

Browse files
john-data-chenjohn-data-chen
committed
docs: update project info
1 parent 1b96649 commit 23f964b

3 files changed

Lines changed: 108 additions & 99 deletions

File tree

‎README.md‎

Lines changed: 57 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,73 +1,85 @@
1-
# Next.js Project Management Tool | Full-Stack Portfolio Project with AI-Assisted Engineering
1+
# Next.js Kanban Board | Full-Stack Portfolio with AI-Assisted Engineering
22

33
[![codecov](https://codecov.io/gh/john-data-chen/next-dnd-starter-kit/graph/badge.svg?token=VM0ZK1S8U5)](https://codecov.io/gh/john-data-chen/next-dnd-starter-kit)
44
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=john-data-chen_next-dnd-starter-kit&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=john-data-chen_next-dnd-starter-kit)
55
[![CI](https://github.com/john-data-chen/next-board/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/john-data-chen/next-board/actions/workflows/CI.yml)
66
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
77

8-
## About This Project
8+
A production-grade Kanban board built with Next.js, demonstrating technical decision-making, quality engineering, and AI-assisted development practices. This is the monolithic origin — see below for how it evolved into a multi-platform monorepo.
99

10-
A production-grade Kanban board application. Showcases engineering practices, decision-making and AI-assisted optimization for senior full-stack roles.
11-
12-
**[Live Demo](https://next-dnd-starter-kit.vercel.app)** | **[Monorepo Evolution](https://github.com/john-data-chen/turborepo-starter-kit)**
10+
**[Live Demo](https://next-dnd-starter-kit.vercel.app)**
1311

1412
<img src="./public/assets/Screen_Recording.gif" alt="Demo" width="270" height="579">
1513

1614
---
1715

16+
## Monorepo Evolution
17+
18+
This project was strategically re-architected through three stages, each driven by a clear engineering rationale:
19+
20+
| Stage | Architecture | Key Decision |
21+
| :---- | :----------- | :----------- |
22+
| **1. Monolith** | Next.js full-stack (this repo) | Ship fast, validate product-market fit with a single deployable unit |
23+
| **2. Decoupled** | Next.js frontend + Nest.js backend | Separate concerns for independent team scaling and deployment cycles |
24+
| **3. Multi-Platform** | [Turborepo monorepo](https://github.com/john-data-chen/turborepo-starter-kit) | Share business logic (state, types, i18n, validation) across Web and Mobile |
25+
26+
The monorepo evolution introduces shared packages (`@repo/store`, `@repo/i18n`, `@repo/ui`) that enable a write-once approach for state management, validation, and types — while each platform (Next.js web, Expo mobile, Nest.js API) maintains full control over its UI and deployment. This mirrors the architectural pattern used by teams scaling from a single product to a platform.
27+
28+
---
29+
1830
## Engineering Metrics
1931

20-
| Metric | Result |
21-
| -------------- | ------------------------------------------------------------- |
22-
| Test Coverage | **80%+** via Vitest (unit + integration) |
23-
| Code Quality | **SonarQube A** across Security, Reliability, Maintainability |
24-
| Performance | **Lighthouse 90+** on all categories |
25-
| E2E Validation | Cross-browser (Chrome, Safari, Edge) via Playwright |
26-
| CI/CD Pipeline | GitHub Actions → SonarQube + Codecov → Vercel |
32+
| Metric | Result |
33+
| ------ | ------ |
34+
| Test Coverage | **80%+** via Vitest (unit + integration) |
35+
| Code Quality | **SonarQube A** across Security, Reliability, Maintainability |
36+
| Performance | **Lighthouse 90+** on all categories |
37+
| E2E Validation | Cross-browser (Chrome, Safari, Edge) via Playwright |
38+
| CI/CD Pipeline | GitHub Actions → SonarQube + Codecov → Vercel |
2739

2840
<img src="./public/assets/lighthouse_scores.png" alt="Lighthouse Scores" width="380" height="125">
2941

3042
---
3143

3244
## Technical Decisions
3345

46+
### Architecture
47+
48+
| Type | Choice | Rationale |
49+
| ---- | ------ | --------- |
50+
| Framework | Next.js (App Router) | SSG for static pages, SSR for dynamic content |
51+
| State | Zustand | 40% less boilerplate than Redux, simpler testing |
52+
| Forms | React Hook Form + Zod | Type-safe validation, composable schemas |
53+
| Database | MongoDB + Mongoose | Document model fits board/project/task hierarchy |
54+
| Auth | Better Auth | OAuth support |
55+
| DnD | dnd-kit | Lightweight, accessible, extensible |
56+
| i18n | next-intl | App Router native support |
57+
| UI | Tailwind CSS + Shadcn/ui | Consistent design system, rapid iteration |
58+
3459
### Quality Assurance
3560

36-
| Type | Tool | Rationale |
37-
| ----------------- | ---------- | -------------------------------------------- |
38-
| Unit/Integration | Vitest | Faster than Jest, native ESM, simpler config |
39-
| E2E | Playwright | Cross-browser support, lighter than Cypress |
40-
| Static Analysis | SonarQube | Enterprise-grade quality gates in CI |
41-
| Coverage Tracking | Codecov | Automated PR integration |
61+
| Type | Tool | Rationale |
62+
| ---- | ---- | --------- |
63+
| Unit/Integration | Vitest | Faster than Jest, native ESM, simpler config |
64+
| E2E | Playwright | Cross-browser support, lighter than Cypress |
65+
| Static Analysis | SonarQube | Enterprise-grade quality gates in CI |
66+
| Coverage Tracking | Codecov | Automated PR integration |
4267

4368
**Testing Strategy:**
4469

4570
- Unit tests target store logic, validations, and isolated components
4671
- E2E tests validate critical flows (auth)
4772
- Every PR triggers the full pipeline before merge
4873

49-
### Architecture
50-
51-
| Type | Choice | Rationale |
52-
| --------- | ------------------------ | ------------------------------------------------ |
53-
| Framework | Next.js (App Router) | SSG for static pages, SSR for dynamic content |
54-
| State | Zustand | 40% less boilerplate than Redux, simpler testing |
55-
| Forms | React Hook Form + Zod | Type-safe validation, composable schemas |
56-
| Database | MongoDB + Mongoose | Document model fits board/project/task hierarchy |
57-
| Auth | Better Auth | OAuth support |
58-
| DnD | dnd-kit | Lightweight, accessible, extensible |
59-
| i18n | next-intl | App Router native support |
60-
| UI | Tailwind CSS + Shadcn/ui | Consistent design system, rapid iteration |
61-
6274
### Developer Experience
6375

64-
| Tool | Purpose |
65-
| ---------- | ------------------------------------------------- |
66-
| Turbopack | Rust bundler with filesystem caching for fast HMR |
67-
| Oxlint | 50-100x faster than ESLint, clearer diagnostics |
68-
| Oxfmt | 30x faster formatter than Prettier |
69-
| Husky | Pre-commit quality enforcement |
70-
| Commitizen | Conventional commits for clean history |
76+
| Tool | Purpose |
77+
| ---- | ------- |
78+
| Turbopack | Rust bundler with filesystem caching for fast HMR |
79+
| Oxlint | 50-100x faster than ESLint, clearer diagnostics |
80+
| Oxfmt | 30x faster formatter than Prettier |
81+
| Husky | Pre-commit quality enforcement |
82+
| Commitizen | Conventional commits for clean history |
7183

7284
---
7385

@@ -85,13 +97,13 @@ A production-grade Kanban board application. Showcases engineering practices, de
8597

8698
## Permission Model
8799

88-
| Capability | Owner | Member |
89-
| ------------------- | ----- | ------ |
90-
| Manage Board | Yes | No |
91-
| Create Project/Task | Yes | Yes |
92-
| Edit All Content | Yes | No |
93-
| Edit Own Content | Yes | Yes |
94-
| View All Content | Yes | Yes |
100+
| Capability | Owner | Member |
101+
| ---------- | ----- | ------ |
102+
| Manage Board | Yes | No |
103+
| Create Project/Task | Yes | Yes |
104+
| Edit All Content | Yes | No |
105+
| Edit Own Content | Yes | Yes |
106+
| View All Content | Yes | Yes |
95107

96108
---
97109

‎ai_docs/PROMPTS.md‎

Lines changed: 50 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,11 @@
11
# AI Guidelines
22

3-
## AI Assistant Behavioral Framework
4-
5-
- **MANDATORY**: Check for `karpathy-guidelines` skill for ANY coding task.
6-
- **Check MCP/skills before execution**:
7-
- Verify available and enabled tools
8-
- Suggest and confirm with the user which MCP/skill to use
9-
- Recommend missing ones if useful
10-
- **Convention First**: Always analyze existing patterns, libraries, and code style before making changes
11-
- **Verify, Then Act**: Never assume dependencies or commands exist - always verify through package.json or config files
12-
- **Test-Driven Changes**: Look for existing tests, run them to understand behavior, write tests before implementing features
13-
- **Incremental Verification**: Run lint, type-check, test, and build commands after every significant change
3+
## Before Every Task
4+
5+
1. **Load `karpathy-guidelines` skill** — mandatory for any coding task.
6+
2. **Identify applicable skills** from the Skill Dispatch Guide below. Load them before writing code.
7+
3. **Check available MCP servers** — use them when they save time (e.g., `context7-mcp` for package docs, `nextjs-mcp` for dev server diagnostics).
8+
4. **Read before writing** — analyze existing patterns, libraries, and code style. Never assume a dependency or command exists without verifying via `package.json` or config files.
149

1510
> [!TIP]
1611
> If need to check package info, use `context7-mcp` if installed and enabled.
@@ -20,43 +15,57 @@
2015

2116
When a task matches conditions below, load the corresponding skill **before writing code**.
2217

23-
### Universal Optimization Skills (CHECK FIRST, in `ai_docs/skills/ai-optimization/`)
18+
### Universal (always check first)
19+
20+
| Condition | Skill |
21+
| :-------- | :---- |
22+
| **Any coding task** — writing, refactoring, fixing bugs | `karpathy-guidelines` |
23+
24+
### Web
2425

25-
| Condition (when the task involves...) | Skill to Use |
26-
| :---------------------------------------------------------------------------------------------------------------------------------- | :-------------------- |
27-
| **ANY coding task** (writing, refactoring, fixing bugs). **ALWAYS** load this skill first to ensure high-quality, surgical changes. | `karpathy-guidelines` |
26+
| Condition | Skill |
27+
| :-------- | :---- |
28+
| Next.js file conventions, RSC, data fetching, metadata, route handlers, async APIs | `next-best-practices` |
29+
| `use cache` directive, PPR, cacheLife, cacheTag, updateTag, static/dynamic mix | `next-cache-components` |
30+
| Component API design, compound components, boolean prop cleanup, render props | `vercel-composition-patterns` |
31+
| React/Next.js performance: re-renders, bundle size, waterfalls, memoization | `vercel-react-best-practices` |
32+
| UI review, accessibility audit, UX compliance, design guidelines | `web-design-guidelines` |
2833

29-
### Web Skills (`ai_docs/skills/web/`)
34+
Skills are in `ai_docs/skills/`. Copy the ones you need to your AI tool's skill directory (e.g., `.claude/skills/` for Claude Code).
3035

31-
| Condition (when the task involves...) | Skill to Use |
32-
| :--------------------------------------------------------------------------------- | :---------------------------- |
33-
| Next.js file conventions, RSC, data fetching, metadata, route handlers, async APIs | `next-best-practices` |
34-
| `use cache` directive, PPR, cacheLife, cacheTag, updateTag, static/dynamic mix | `next-cache-components` |
35-
| Component API design, compound components, boolean prop cleanup, render props | `vercel-composition-patterns` |
36-
| React/Next.js performance: re-renders, bundle size, waterfalls, memoization | `vercel-react-best-practices` |
37-
| UI review, accessibility audit, UX compliance, design guidelines | `web-design-guidelines` |
36+
## Project Context
3837

39-
## Project Overview
38+
### Tech Stack
39+
40+
Check `package.json` for exact versions. Key stack: **Next.js (App Router), React, TypeScript (strict), TailwindCSS, Vitest, PNPM**.
4041

4142
### Repository Structure
4243

43-
| Type | Path | Description |
44-
| ---------- | -------------------- | ------------------------------------- |
45-
| Tests | `__tests__` | Unit and E2E tests |
46-
| Database | `database` | docker-compose |
47-
| i18n | `messages` | i18n translations |
48-
| Router | `src/app/` | Next.js App Router |
49-
| Components | `src/components/` | React components |
50-
| Components | `src/components/ui/` | Shadcn UI components |
51-
| Constants | `src/constants/` | Constants |
52-
| Hooks | `src/hooks/` | Custom hooks |
53-
| Library | `src/lib/db` | Database functions |
54-
| State | `src/lib/stores/` | Zustand stores (auth, board, project) |
55-
| Styles | `src/styles/` | Global css |
44+
| Type | Path | Description |
45+
| ---- | ---- | ----------- |
46+
| Tests | `__tests__` | Unit and E2E tests |
47+
| Database | `database` | docker-compose |
48+
| i18n | `messages` | i18n translations |
49+
| Router | `src/app/` | Next.js App Router |
50+
| Components | `src/components/` | React components |
51+
| Components | `src/components/ui/` | Shadcn UI components |
52+
| Constants | `src/constants/` | Constants |
53+
| Hooks | `src/hooks/` | Custom hooks |
54+
| Library | `src/lib/db` | Database functions |
55+
| State | `src/lib/stores/` | Zustand stores (auth, board, project) |
56+
| Styles | `src/styles/` | Global css |
5657

5758
Shadcn UI components are in `src/components/ui`. Modify `src/styles/globals.css` and `src/components` first; only modify Shadcn UI components as a last resort.
5859

59-
## Essential Commands
60+
### Naming Conventions
61+
62+
- **Components**: PascalCase (`DatePicker.tsx`)
63+
- **Utilities**: camelCase (`dateUtils.ts`)
64+
- **Constants**: UPPER_SNAKE_CASE (`API_ENDPOINTS.ts`)
65+
- **Types**: PascalCase interfaces (`UserData`, `ApiResponse`)
66+
- **Commits**: [Conventional Commits](https://conventionalcommits.org/) — `feat(scope): description` / `fix(scope): description`
67+
68+
## Commands
6069

6170
Dev server is already running (`pnpm dev`). Do not start it again.
6271

@@ -65,23 +74,11 @@ pnpm install # Install all dependencies
6574
pnpm build # Build for production
6675
```
6776

68-
### Verification Workflow
77+
### After Every Task
6978

7079
```bash
7180
git add /path/to/your/file.ts # Stage file for linting
72-
pnpm lint-staged # Run linter and prettier
81+
pnpm lint-staged # Run linter and formatter
7382
```
7483

75-
After every task: verify with `pnpm lint-staged` → fix errors → unstage files → suggest a Conventional Commit message. Never commit for the user.
76-
77-
## Tech Stack
78-
79-
Check `package.json` for exact versions. Key stack: Next.js (App Router), React, TypeScript (strict), TailwindCSS, Vitest, PNPM.
80-
81-
## Naming Conventions
82-
83-
- **Components**: PascalCase (`DatePicker.tsx`)
84-
- **Utilities**: camelCase (`dateUtils.ts`)
85-
- **Constants**: UPPER_SNAKE_CASE (`API_ENDPOINTS.ts`)
86-
- **Types**: PascalCase interfaces (`UserData`, `ApiResponse`)
87-
- **Commits**: [Conventional Commits](https://conventionalcommits.org/) — `feat(scope): description` / `fix(scope): description`
84+
Fix all errors → unstage files → suggest a Conventional Commit message. **Never commit for the user.**

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,4 +107,4 @@
107107
"unrs-resolver"
108108
]
109109
}
110-
}
110+
}

0 commit comments

Comments
 (0)