engel/IMPLEMENTATION_PLAN.md

Academy Engel Implementation Plan

This document is the working implementation checklist for the academy engel project.

Product Goal

Build Academy Engel as a single full-stack Next.js application with:

• App Router
• PostgreSQL
• Prisma ORM
• bilingual public website (en, de)
• admin CMS with role-based access
• lead capture for contact and placement requests

Phase 1 does not include:

• student accounts
• payment flow
• enrollment automation
• learning portal features

Current Status

Completed

• Next.js public site structure created with App Router
• locale-based public routes added under /{locale}
• homepage recreated in Next.js based on index.html
• local image assets downloaded into public/images
• reusable public components added
• FAQ interaction added on the frontend
• Tailwind moved to local project setup
• .gitignore added
• initial Prisma schema draft added
• .env.example added
• npm run build passes on the current frontend structure

Not Completed Yet

• Prisma runtime installation and database wiring
• actual PostgreSQL connection
• seed script with real initial content
• auth system
• admin CMS
• CRUD actions
• lead persistence
• route protection
• public pages reading from database instead of mock content

Phase 1: Environment and Infrastructure

1. Package and Tooling Setup

• Run a clean install for all dependencies in package.json
• Confirm next-auth, prisma, @prisma/client, bcryptjs, and zod are installed correctly
• Resolve the @next/swc version mismatch warning
• Verify postcss and Tailwind setup is stable in dev and build modes

2. Environment Variables

• Create a real .env.local from .env.example
• Set DATABASE_URL for PostgreSQL
• Set NEXTAUTH_SECRET
• Set NEXTAUTH_URL
• Document local development env requirements

3. Database Bootstrapping

• Create PostgreSQL database for local development
• Run prisma generate
• Create first Prisma migration
• Run prisma migrate dev
• Confirm schema is applied successfully

Phase 2: Database and Data Layer

4. Finalize Prisma Schema

• Review and refine User
• Review and refine Course
• Review and refine Teacher
• Review and refine Post
• Review and refine FaqItem
• Review and refine Lead
• Review and refine SiteSetting
• Add timestamps and indexes where needed
• Confirm status enums and role enums are final for phase 1

5. Shared Server Utilities

• Add Prisma client singleton helper
• Add auth helper utilities
• Add role guard helpers
• Add shared form validation schemas with zod
• Add content mapping helpers for en and de

6. Seed Data

• Replace placeholder seed script in prisma/seed.mjs
• Seed admin user
• Seed editor user
• Seed courses
• Seed teachers
• Seed blog posts
• Seed FAQ items
• Seed site settings
• Ensure seeded content matches the current homepage direction

Phase 3: Public Website Integration

7. Replace Mock Content with Database Reads

• Remove dependency on static content in lib/site-data.js for production data access
• Fetch homepage content from Prisma
• Fetch courses list from Prisma
• Fetch course detail pages from Prisma
• Fetch teachers list from Prisma
• Fetch blog list from Prisma
• Fetch blog detail pages from Prisma
• Fetch FAQ content from Prisma
• Fetch site settings from Prisma

8. Public Route Behavior

• Keep /{locale} routing as the public structure
• Ensure both en and de render correct localized content
• Confirm metadata is generated per locale/page
• Handle not-found states for missing course/blog slugs
• Add stable navigation behavior between locales

9. Public Forms

• Connect contact form to Lead table
• Connect placement-test form to Lead table
• Validate form submissions with zod
• Store locale on lead records
• Store type as CONTACT or PLACEMENT
• Add success and failure UI states

Phase 4: Authentication and Authorization

10. Auth Setup

• Configure Auth.js / NextAuth for App Router
• Add credentials provider
• Store password hashes with bcryptjs
• Implement login page for admin area
• Implement session handling
• Implement logout flow

11. Role-Based Access

• Define ADMIN and EDITOR permissions clearly
• Protect all /admin routes
• Restrict user management to ADMIN
• Allow content management for ADMIN and EDITOR
• Prevent unauthorized access to server actions

Phase 5: Admin CMS

12. Admin App Structure

• Create /admin layout
• Add sidebar/navigation
• Add dashboard overview page
• Add shared admin form styles/components
• Add loading and empty states

13. Content Management Screens

• Courses list/create/edit/publish UI
• Teachers list/create/edit/publish UI
• Blog posts list/create/edit/publish UI
• FAQ list/create/edit UI
• Site settings editor
• Leads list/detail/update status UI
• Users list/create/edit UI

14. Admin CRUD Backend

• Create server actions for courses
• Create server actions for teachers
• Create server actions for blog posts
• Create server actions for FAQ items
• Create server actions for site settings
• Create server actions for leads
• Create server actions for users
• Add revalidation after mutations

Phase 6: Quality, UX, and Cleanup

15. Frontend Cleanup

• Compare homepage visually against index.html
• Tighten spacing, typography, and section order where needed
• Improve mobile navigation behavior
• Improve button/link consistency
• Decide whether any remaining animations should stay CSS-only or be expanded

16. Content and Encoding Cleanup

• Ensure no broken encoding remains anywhere in UI or data
• Normalize copy across English and German content
• Replace any temporary ASCII-only fallback text if desired
• Make sure CMS fields support the intended localized content format

17. Codebase Cleanup

• Remove obsolete prototype code
• Remove unused dependencies if any
• Split oversized files if they become hard to maintain
• Keep server and client boundaries clean
• Review naming consistency across routes, models, and UI

Testing Checklist

18. Technical Verification

• npm run build passes
• Prisma client generates successfully
• Prisma migrations run on a clean database
• Seed script runs successfully
• No broken route imports or alias issues

19. Public Website Verification

• /en renders correctly
• /de renders correctly
• course listing and detail pages work
• blog listing and detail pages work
• teachers page works
• FAQ page works
• contact page works
• placement page works
• all local images load correctly

20. Auth and Admin Verification

• admin can sign in
• editor can sign in
• anonymous user cannot access admin
• admin can manage users
• editor cannot manage users
• admin and editor can manage content

21. Lead Verification

• contact form creates a Lead
• placement form creates a Lead
• lead locale is stored correctly
• lead status can be updated in admin

Recommended Execution Order

1. Finish dependency installation and fix package/runtime issues
2. Connect PostgreSQL and Prisma
3. Write real seed data
4. Replace frontend mock data with database reads
5. Wire contact and placement forms to the database
6. Add authentication
7. Build admin layout and content CRUD
8. Add role protections and user management
9. Final visual cleanup and testing

Important Notes

• The current homepage implementation is a frontend milestone, not the final data architecture.
• The current lib/site-data.js should be treated as temporary mock content until Prisma-backed queries replace it.
• The CMS can be visually simple in phase 1, but permissions and data integrity must be correct.
• Media storage is external-URL based in the original plan, but local copies of current marketing images are now included for the public demo.