Project architecture setup

[MohamedMouloudj]

Description

Scaffold the base folder structure for the web project according to the agreed architecture. No components, no layout, no placeholder UI.

Folders to create

• components/ - reusable UI components
• components/ui/ - shadcn components only
• app/api/ - Next.js route handlers
• lib/ - third party configs and utility functions
• hooks/ - custom React hooks
• types/ - shared TypeScript types (API responses, common types)
• services/ - reusable backend caller methods as classes, using fetch (no axios)
• services/actions/ - Next.js server actions

Architecture rules (add as a comment or README in each folder)

• Never use axios, use native fetch for edge compatibility
• Services must be classes
• Server actions go under services/actions/
• shadcn components go under components/ui/ only
• Custom hooks go under hooks/, never inline in components
• Types shared across features go under types/
• Always consider SEO, use generateMetadata where relevant

Caching strategy (decision required)

Next.js 16 introduced cacheComponents in next.config.ts. When enabled, all data fetching is dynamic by default unless explicitly cached with the use cache directive at the page, component, or function level. This replaces the old model where fetches were cached by default.

The team must decide before writing any data fetching code:

Option A: enable cacheComponents: true

• Data fetching is dynamic by default (always fresh)
• Use use cache explicitly on components or functions that should be cached
• Pairs with cacheLife and cacheTag for fine-grained control
• Recommended for apps with user-specific or frequently changing data

// next.config.ts
const nextConfig: NextConfig = {
  cacheComponents: true,
}

// cache a specific server component or function
'use cache'
export async function getVideos() { ... }

Option B: do not enable cacheComponents

• Stick with the previous Next.js caching model
• fetch requests are cached by default, opt out with cache: 'no-store'
• Less explicit but more familiar

Given that this platform serves personalized, user-specific content (child profiles, playlists, access policies), Option A is recommended. But the decision must be agreed on by the team before any data fetching is written.

Reference: https://nextjs.org/docs/app/api-reference/config/next-config-js/cacheComponents

Acceptance Criteria

• All folders exist with a .gitkeep or a short explanatory comment file
• No placeholder components or layout are created
• next.config.ts reflects the agreed caching strategy
• Folder structure matches the architecture above

[snakefood3232]

I'll scaffold the web project architecture exactly as specified, including the folder structure and architecture rules in README files. I'd handle this by setting up the base structure with proper TypeScript configs and addressing the caching strategy decision upfront. Can have a PR ready in a few hours—I've built multiple Next.js 14+ codebases with this exact service/action architecture.