Vuexy Next.js Frontend Customisation

Status: 🟡 In progress — research done, customisation not started
Started: 2026-05-12
Goal: Use Vuexy Next.js 15 as the base template and customise it into the app frontend using Claude Code to navigate and modify the codebase

Template details

• Product: Vuexy by PixInvent (sold on ThemeForest)
• Stack: Next.js 15 (App Router + SSR), Material UI v5, Tailwind CSS
• Includes: 10 pre-built apps (Email, Chat, Calendar, Kanban…), 6 layout options
• Version note: Use the new App Directory Routing version — Pages Router version is deprecated
• License note: Each end product / client requires its own license

Plan

1. Get Vuexy Next.js package set up locally
2. Point Claude Code at the vuexy-next.js/ directory
3. Walk Claude Code through the template structure
4. Provide app requirements → let Claude Code modify components, routes, and styles

Progress log

2026-05-12 (morning)

• Confirmed Vuexy Next.js 15 version exists with App Router + MUI v5 + Tailwind ✅
• Started conversation with Claude to plan approach — cut off before specifying app details
• Claude asked: where is the project located? what app are you building? what’s the tech stack?

2026-05-12 (afternoon)

• Answered Claude’s questions: local machine, SaaS / Dashboard, all phases ✅
• Received 4-phase Claude Code prompt (ready to paste into claude):
  • Phase 1 — Audit & Map: scan entire project, list routes, config files, mock data locations
  • Phase 2 — Branding: replace Vuexy/PixInvent branding, update colors (#2563EB primary)
  • Phase 3 — Clean demo: remove eCommerce/gaming/crypto pages; keep Auth, Dashboard, Users, Settings
  • Phase 4 — SaaS foundation: /dashboard, /users, /settings, /auth/login, /auth/register
• Made monorepo decision: single repo with frontend/, backend/, docker-compose.yml ✅
  • Backend: Django + Ninja (REST API)
  • DB: SQLite for dev, Postgres for prod (switched in settings.py via DEBUG flag)
• Discussed CLAUDE.md for the project root to give Claude Code permanent context

Monorepo structure (decided)

my-app/
├── frontend/          # Next.js (Vuexy-based)
├── backend/           # Django + Ninja
├── docker-compose.yml
├── .env.example
├── CLAUDE.md
└── README.md

Open tasks

• Set up monorepo folder structure locally
• Download / set up Vuexy Next.js package into frontend/
• Create CLAUDE.md at repo root with stack, dev commands, git flow
• Run Phase 1 audit in Claude Code (paste the prompt from the conversation)
• Review Phase 1 output then continue with Phases 2-4

Reference

• Vuexy ThemeForest listing for license details
• reference/cicd-django-nextjs — for the backend pairing with this frontend

2026-05-12 (evening)

Codebase documentation strategy finalised — comprehensive prompt written for Claude Code to produce 12 documentation files under claude-docs/ in the Vuexy source directory. Purpose: create a persistent context map Claude can always refer to.

claude-docs/ file inventory

SKILL.md structure

• Codebase identity (one paragraph)
• Golden rules (10–15 must-follow conventions)
• Component quick-reference table (Name / Location / Use When)
• Layout quick-reference table
• Pattern cheatsheet (add page, add protected route, add chart, add form, etc.)
• Compact directory map
• Anti-patterns

How to use

# 1. Open Claude Code in the Vuexy source directory
cd ~/projects/vuexy-next.js
claude
 
# 2. Paste the Phase 1 documentation prompt
# (saved from "Next.js template framework contents" chat — 2026-05-12)
 
# 3. Let it run — writes all 12 files to claude-docs/
 
# 4. Every future build task starts with:
# "Read claude-docs/SKILL.md first, then..."

• Paste Phase 1 documentation prompt into Claude Code (Vuexy dir)
• Review SKILL.md output — verify Golden Rules are accurate
• Add claude-docs/ to .gitignore or commit as part of the repo

2026-05-13

Codebase scan & SKILL.md approach confirmed — second comprehensive Claude Code prompt written: reads all claude-docs/ files + spot-checks real source, then writes a final SKILL.md with 21 structured sections.

Key additions today:

• Confirmed SKILL.md must contain: Absolute Rules, Directory Map, Task Playbook, Anti-Patterns, Quick-Start Checklist, File Finder (21 sections total)
• Monorepo structure reconfirmed: frontend/ + backend/ + docker-compose.yml + CLAUDE.md
• CI/CD + Docker dev environment fully designed (self-hosted runner, blue-green deploy) → see reference/docker-dev-environment and reference/cicd-django-nextjs

Open tasks updated:

• Set up monorepo folder locally
• Download Vuexy Next.js into frontend/
• Create CLAUDE.md at repo root
• Run Phase 1 codebase scan in Claude Code
• Run Phase 2 SKILL.md generation
• Verify SKILL.md Golden Rules against real source files
• Set up self-hosted GitHub Actions runner on local server

2026-05-15

Multi-agent team prompt architected for User Management phases 4–6.

• Phases 1–3 (T001–T067) complete. Remaining scope: Phase 4 (T068–T088, Roles & Permissions), Phase 5 (T089–T112, Deactivate Users), Phase 6 (T113–T125, Polish & Security).
• Created Lead spawn prompt with three permanent agents: django-agent (TDD backend), nextjs-agent (strict TypeScript frontend, waits on API contract), qa-agent (phase gate enforcer).
• API-First rule enforced via progress.md — django-agent posts contract, nextjs-agent begins. Never reversed.
• Phase gate: all tasks + qa-agent PASS → git commit “phase N complete: “.
• Three-layer CLAUDE.md files generated: root (shared contract), backend/CLAUDE.md (Django expertise), frontend/CLAUDE.md (NextJS + Vuexy path reference).
• → See reference/claude-code-multiagent-team for the reusable prompt template.

Open tasks updated:

• Confirm progress.md reflects T001–T067 as complete before running Lead
• Paste Lead prompt into Claude Code to kick off Phase 4
• Monitor phase gate — re-engage if qa-agent posts FAIL
• Set up monorepo folder structure locally
• Download Vuexy Next.js into frontend/
• Create CLAUDE.md at repo root (template ready from 2026-05-15 session)

2026-05-18

Design system clarity and Speckit workflow refined.

Conversation re: NotebookLM vs Claude for the learning-to-implementation pipeline surfaced key clarity on the stack and workflow.

Design system confirmed:

• Vuexy Next.js = MUI v5 + Tailwind CSS (not Shadcn, not Ant Design)
• The design system IS MUI — study MUI component names when prompting Claude for UI output
• Prompt format: use specific MUI component names (e.g. DataGrid, Autocomplete) for better results

Speckit workflow clarified:

• Feed one epic at a time — never vague feature names
• Pre-generate a full epic spec in Claude first → then feed to Speckit
• Speckit generates stories; quality depends on the context you provide
• The long Claude-generated spec is for Claude to write and you to review — not manual work

Pain points acknowledged:

1. Getting LLMs to produce best-practice requirements
2. UX/UI output — functional but visually weak (MUI-specific prompting helps)

Open tasks added:

• Try MUI-specific prompting format for next UI task (use component names in prompt)
• Create one full epic spec in Claude as a template for Speckit workflow

Week of 2026-W20 (Mon 12 – Sun 17 May)

Architecture and documentation strategy fully designed this week. The monorepo structure was confirmed (frontend/ + backend/ + docker-compose.yml), and a comprehensive codebase documentation strategy was built: a Claude Code prompt to generate 12 claude-docs/ files culminating in a SKILL.md context anchor. A full 4-phase customisation plan was created (Audit & Map → Branding → Clean Demo Content → SaaS Foundation Pages). Three-layer CLAUDE.md structure designed for the monorepo: root shared contract, backend/CLAUDE.md (Django/TDD), frontend/CLAUDE.md (TypeScript/React Query). Lead + sub-agent prompt architected for User Management phases 4–6.

Status: 🟡 Architecture complete — Phase 1 audit not yet run.

Open tasks (W21):

• Run Phase 1 Vuexy audit in Claude Code (paste the 12 claude-docs/ prompt)
• Paste Lead agent prompt to kick off User Management Phase 4 (T068–T088)

2026-05-26

Vertical slice approach confirmed as correct build order for the project.

Debated whether to build all backend first (13 weeks) before frontend. Conclusion: wrong for a solo developer. Vertical slices (model → endpoint → frontend component per feature) are the right approach because they deliver visible progress every 1–2 weeks, keep API shape and UI in sync, and prevent motivation collapse. The existing Jira plan already structures work as vertical slices — no reordering needed.

Data model hardening happens in Phase 0–1 (Foundation + Auth) before any feature-specific models, which addresses the one legitimate concern with early frontend work.

→ See reference/vertical-slice-solo-dev for the reusable framework.

Open tasks (unchanged from 2026-05-18):

• Run Phase 1 Vuexy audit in Claude Code (paste the 12 claude-docs/ prompt)
• Paste Lead agent prompt to kick off User Management Phase 4 (T068–T088)
• Download Vuexy Next.js into frontend/
• Create CLAUDE.md at repo root

Week of 2026-W22 (Mon 26 – Sun 31 May)

Confirmed vertical slice as the correct build order for the project (2026-05-26). The debate between all-backend-first vs vertical slices was resolved: for a solo developer with a known spec, vertical slices (model → endpoint → frontend component per feature) are correct. The existing Jira plan already follows this structure — no rework needed. Phase 0–1 handles data model hardening before feature development begins, which removes the only legitimate argument for all-backend-first.

Status: 🟡 Architecture confirmed — Phase 1 audit still not yet run.

Open tasks (W23):

• Run Phase 1 Vuexy audit in Claude Code (paste the 12 claude-docs/ prompt)
• Paste Lead agent prompt to kick off User Management Phase 4 (T068–T088)
• Download Vuexy Next.js into frontend/
• Create CLAUDE.md at repo root