nuxt

.
├── app/
│   ├── app.vue                        # Root component — calls useApp init
│   ├── error.vue                      # Global error page
│   ├── pages/                         # File-based routing
│   │   ├── index.vue
│   │   └── users/
│   │       └── [id].vue
│   ├── layouts/                       # Layout components
│   │   ├── default.vue
│   │   └── dashboard.vue
│   ├── middleware/                    # Route middleware
│   │   ├── auth.ts                    # Global or named auth guard
│   │   └── role.ts
│   ├── plugins/                       # App-level plugins
│   │   ├── analytics.client.ts        # Client-only plugin
│   │   └── sentry.ts
│   ├── components/
│   │   ├── app/                       # Shared application components
│   │   │   ├── AppHeader.vue
│   │   │   ├── AppFooter.vue
│   │   │   └── AppLoadingState.vue
│   │   ├── ui/                        # Independent, reusable UI components (no domain logic)
│   │   │   ├── BaseCard.vue
│   │   │   └── BaseEmptyState.vue
│   │   ├── home/                      # Home page components
│   │   │   ├── HomeHero.vue
│   │   │   ├── HomeLatestArticles.vue
│   │   │   └── HomeFeaturedProducts.vue
│   │   └── user/                      # User module components (matches the user domain)
│   │       ├── list/                  # User list view
│   │       │   ├── UserList.vue       # Orchestrates user list (no "Container" suffix)
│   │       │   ├── UserListItem.vue
│   │       │   └── UserListFilters.vue
│   │       ├── detail/                # User detail view
│   │       │   ├── UserDetail.vue     # Orchestrates user detail
│   │       │   ├── UserProfile.vue
│   │       │   └── UserActivityFeed.vue
│   │       └── add/                   # User add/edit views
│   │           ├── UserAdd.vue        # Orchestrates user creation
│   │           └── UserAddForm.vue
│   ├── composables/                   # Auto-imported composables (filename without "use" prefix)
│   │   ├── app.ts                     # exports useApp()
│   │   ├── pages.ts                   # exports usePages()
│   │   └── user.ts                    # exports useUser()
│   └── stores/                        # Pinia stores (auto-imported via nuxt.config)
│       ├── app.store.ts               # exports useAppStore
│       └── user.store.ts              # exports useUserStore
│
├── server/
│   ├── api/
│   │   ├── app/
│   │   │   └── index.get.ts           # App initialization endpoint
│   │   ├── pages/
│   │   │   ├── index.get.ts           # Home page data endpoint — returns ALL home data
│   │   │   └── users/
│   │   │       └── [id].get.ts        # User page data endpoint — returns ALL user data
│   │   └── user/
│   │       ├── create.post.ts
│   │       └── [id].delete.ts
│   ├── utils/                         # Auto-imported server utilities — flat, one file per domain
│   │   ├── user.ts                    # createUser, findUser, deleteUser — ALL in one file
│   │   ├── product.ts
│   │   └── app.ts
│   └── contexts/                      # NOT auto-imported — explicit imports only
│       ├── shared/
│       │   ├── services/
│       │   │   └── PostgresService.ts
│       │   └── errors/
│       │       └── ServerError.ts
│       └── user/
│           ├── domain/
│           │   ├── User.ts
│           │   ├── UserRepository.ts
│           │   └── UserError.ts
│           ├── application/
│           │   ├── UserCreator.ts
│           │   └── UserFinder.ts
│           └── infrastructure/
│               └── PostgresUserRepository.ts
│
└── shared/
    ├── types/                         # Flat — no subfolders — auto-importable
    │   ├── App.ts                     # App initialization types (interface App)
    │   ├── Page.ts                    # All page types (special — not split by module)
    │   └── User.ts                    # Domain types + AuthUser
    └── utils/                         # Flat — no subfolders — auto-importable
        ├── user.ts                    # Zod schemas and utilities for user module
        └── product.ts

// nuxt.config.ts
export default defineNuxtConfig({
  
  // Define components path without prefix
  components: [
    { path: '@/components', pathPrefix: false },
  ],
  
  // Define Devtools
  devtools: {
    enabled: import.meta.env.DEVTOOLS_ENABLED || false,
    timeline: {
      enabled: true,
    },
  },
  
  // Define CSS
  css: [
    '@/assets/css/main.css',
  ],
  
  // Runtime config
  runtimeConfig: {
    privateConfig: '',
    public: {
      publicConfig: ''
    }
  }
  
  compatibilityDate: '2025-07-15',
  
  // Auto-import stores from app/stores/
  pinia: {
    storesDirs: ['./stores/**.store.ts'],
  },
  
  modules: [
    '@pinia/nuxt',
    '@nuxt/ui', // if using Nuxt UI
    '@nuxtjs/i18n', // if using i18n
  ],
})

// app/pages/index.vue — no imports needed
const pages = usePages()
const { data } = await useAsyncData('home', () => pages.getHomePage())
const userStore = useUserStore()

// server/contexts/user/application/UserCreator.ts
import type { UserRepository } from '../domain/UserRepository'       // explicit import
import type { CreateUserDto } from '../../../../shared/types/User'   // explicit import

export class UserCreator {
  constructor(private readonly repository: UserRepository) {}

  async create(dto: CreateUserDto): Promise<void> {
    // ...
  }
}

// server/api/app/index.get.ts
import type { App } from '~~/shared/types/App'

export default defineEventHandler(async (event): Promise<App> => {
  const [config, user] = await Promise.all([
    getAppConfig(event),
    getAuthUser(event),
  ])

  return { config, user }
})

// app/composables/app.ts
export function useApp() {
  const appStore = useAppStore()
  const userStore = useUserStore()

  async function getAppData(): Promise<App> {
    return $fetch('/api/app')
  }

  async function init(): Promise<void> {
    const data = await getAppData()
    appStore.setConfig(data.config)
    userStore.setCurrentUser(data.user)
  }

  return { init }
}

<!-- app/app.vue -->
<script setup lang="ts">
const { init } = useApp()

// callOnce ensures this runs once on SSR and not again on client hydration
await callOnce(init)

// If using nuxt-i18n, re-init on locale change:
// const { locale } = useI18n()
// watch(locale, init)
</script>

<template>
  <NuxtLayout>
    <NuxtPage />
  </NuxtLayout>
</template>

// shared/types/App.ts
export interface App {
  config: AppConfig
  user: User | null
}

export interface AppConfig {
  featureFlags: Record<string, boolean>
  locale: string
}

// server/api/pages/index.get.ts  →  app/pages/index.vue
import type { HomePageData } from '~~/shared/types/Page'

export default defineEventHandler(async (event): Promise<HomePageData> => {
  const [banner, products] = await Promise.all([
    getHeroBanner(event),
    getFeaturedProducts(event),
  ])

  return { banner, products }
})

// server/api/pages/users/[id].get.ts  →  app/pages/users/[id].vue
import type { UserPageData } from '~~/shared/types/Page'

export default defineEventHandler(async (event): Promise<UserPageData> => {
  const id = getRouterParam(event, 'id')!

  const [user, activity] = await Promise.all([
    findUser(event, id),
    getUserActivity(event, id),
  ])

  return { user, activity }
})

// app/composables/pages.ts
export function usePages() {
  async function getHomePage(): Promise<HomePageData> {
    return $fetch('/api/pages')
  }

  async function getUserPage(id: string): Promise<UserPageData> {
    return $fetch(`/api/pages/users/${id}`)
  }

  return { getHomePage, getUserPage }
}

// shared/types/Page.ts
export interface HomePageData {
  banner: Banner
  products: Product[]
}

export interface UserPageData {
  user: User
  activity: UserActivity[]
}

export interface Banner {
  title: string
  imageUrl: string
  ctaLabel: string
  ctaUrl: string
}

// server/api/user/create.post.ts
import type { User } from '~~/shared/types/User'

export default defineEventHandler(async (event): Promise<User> => {
  const body = await readValidatedBody(event, createUserSchema.parse)
  return createUser(event, body)
})

// server/api/user/[id].delete.ts
export default defineEventHandler(async (event): Promise<void> => {
  const id = getRouterParam(event, 'id')!
  await deleteUser(event, id)
})

// app/composables/user.ts
export function useUser() {
  const userStore = useUserStore()

  async function createUser(dto: CreateUserDto): Promise<User> {
    const user = await $fetch('/api/user/create', {
      method: 'POST',
      body: dto,
    })
    userStore.addUser(user)
    return user
  }

  async function deleteUser(id: string): Promise<void> {
    await $fetch(`/api/user/${id}`, { method: 'DELETE' })
    userStore.removeUser(id)
  }

  return { createUser, deleteUser }
}

server/contexts/
└── user/
    ├── domain/
    │   ├── User.ts                    # Domain entity
    │   ├── UserRepository.ts          # Repository interface
    │   └── UserError.ts               # Domain errors
    ├── application/
    │   ├── UserCreator.ts             # Use case
    │   └── UserFinder.ts              # Use case
    └── infrastructure/
        └── PostgresUserRepository.ts  # Concrete implementation

// server/contexts/user/domain/User.ts
export interface User {
  id: string
  name: string
  email: string
  createdAt: Date
}

// server/contexts/user/domain/UserRepository.ts
import type { User } from './User'
import type { CreateUserDto } from '../../../../shared/types/User'

export interface UserRepository {
  findById(id: string): Promise<User | null>
  create(dto: CreateUserDto): Promise<User>
  delete(id: string): Promise<void>
}

// server/contexts/user/application/UserCreator.ts
import type { UserRepository } from '../domain/UserRepository'
import type { CreateUserDto } from '../../../../shared/types/User'
import type { User } from '../domain/User'
import { UserError } from '../domain/UserError'

export class UserCreator {
  constructor(private readonly repository: UserRepository) {}

  async create(dto: CreateUserDto): Promise<User> {
    const existing = await this.repository.findByEmail(dto.email)
    if (existing) throw new UserError('EMAIL_ALREADY_EXISTS', dto.email)
    return this.repository.create(dto)
  }
}

// server/contexts/user/infrastructure/PostgresUserRepository.ts
import type { UserRepository } from '../domain/UserRepository'
import type { User } from '../domain/User'
import type { CreateUserDto } from '../../../../shared/types/User'
import { PostgresService } from '../../shared/services/PostgresService'

export class PostgresUserRepository implements UserRepository {
  constructor(private readonly db: PostgresService) {}

  async findById(id: string): Promise<User | null> {
    return this.db.query('SELECT * FROM users WHERE id = $1', [id])
  }

  async create(dto: CreateUserDto): Promise<User> {
    return this.db.query(
      'INSERT INTO users (name, email) VALUES ($1, $2) RETURNING *',
      [dto.name, dto.email],
    )
  }

  async delete(id: string): Promise<void> {
    await this.db.query('DELETE FROM users WHERE id = $1', [id])
  }
}

// server/utils/user.ts — ALL user utilities in one file
import { UserCreator } from '~~/server/contexts/user/application/UserCreator'
import { UserFinder } from '~~/server/contexts/user/application/UserFinder'
import { PostgresUserRepository } from '~~/server/contexts/user/infrastructure/PostgresUserRepository'
import { PostgresService } from '~~/server/contexts/shared/services/PostgresService'
import type { CreateUserDto } from '~~/shared/types/User'
import type { User } from '~~/shared/types/User'
import type { H3Event } from 'h3'

export async function createUser(event: H3Event, dto: CreateUserDto): Promise<User> {
  const db = new PostgresService()
  const repository = new PostgresUserRepository(db)
  const creator = new UserCreator(repository)
  return creator.create(dto)
}

export async function findUser(event: H3Event, id: string): Promise<User> {
  const db = new PostgresService()
  const repository = new PostgresUserRepository(db)
  const finder = new UserFinder(repository)
  return finder.find(id)
}

export async function deleteUser(event: H3Event, id: string): Promise<void> {
  const db = new PostgresService()
  const repository = new PostgresUserRepository(db)
  await repository.delete(id)
}

export async function getUserActivity(event: H3Event, id: string): Promise<UserActivity[]> {
  // ...
}

// shared/types/User.ts
export interface User {
  id: string
  name: string
  email: string
  role: UserRole
  roles: UserRole[]    // for authenticated user — roles array
  createdAt: string
}

export interface CreateUserDto {
  name: string
  email: string
  role: UserRole
}

export enum UserRole {
  Admin = 'admin',
  User = 'user',
}

// shared/utils/user.ts — ALL user schemas and utilities in one file
import { z } from 'zod'
import { UserRole } from '../types/User'

export const createUserSchema = z.object({
  name: z.string().min(2).max(100),
  email: z.string().email(),
  role: z.nativeEnum(UserRole),
})

export type CreateUserInput = z.infer<typeof createUserSchema>

export function formatUserDisplayName(user: { name: string; email: string }): string {
  return `${user.name} <${user.email}>`
}

<!-- app/pages/index.vue -->
<script setup lang="ts">
const { getHomePage } = usePages()

const { data, status } = await useAsyncData('home', getHomePage)
</script>

<template>
  <div>
    <Home
      v-if="data"
      :data="data"
    />
    <AppLoadingState v-else-if="status === 'pending'" />
  </div>
</template>

<!-- app/pages/users/[id].vue -->
<script setup lang="ts">
const route = useRoute()
const { getUserPage } = usePages()

const { data, status } = await useAsyncData(
  `user-${route.params.id}`,
  () => getUserPage(route.params.id as string),
)
</script>

<template>
  <UserDetail
    v-if="data"
    :data="data"
  />
</template>

<!-- app/components/user/detail/UserDetail.vue -->
<script setup lang="ts">
import type { UserPageData } from '~/shared/types/Page'

const props = defineProps<{
  data: UserPageData
}>()

const userStore = useUserStore()
const { deleteUser } = useUser()

// Hydrate store with server data
userStore.setUser(props.data.user)

// Derived state
const isCurrentUser = computed(() =>
  userStore.currentUser?.id === props.data.user.id
)

async function handleDelete(): Promise<void> {
  await deleteUser(props.data.user.id)
  await navigateTo('/users')
}
</script>

<template>
  <div>
    <UserProfile
      :user="data.user"
      :is-current-user="isCurrentUser"
      @delete="handleDelete"
    />
    <UserActivityFeed :activities="data.activity" />
  </div>
</template>

<!-- app/components/home/HomeLatestArticles.vue — presentational, part of Home -->
<script setup lang="ts">
import type { Article } from '~/shared/types/Page'

defineProps<{
  articles: Article[]
}>()
</script>

<template>
  <section>
    <h2>Latest Articles</h2>
    <ul>
      <li v-for="article in articles" :key="article.id">
        {{ article.title }}
      </li>
    </ul>
  </section>
</template>

components/user/
├── list/
│   ├── UserList.vue           # Orchestrates list view (connects store, composables)
│   ├── UserListItem.vue       # Presentational — one user row
│   └── UserListFilters.vue    # Presentational — filter controls
├── detail/
│   ├── UserDetail.vue         # Orchestrates detail view
│   ├── UserProfile.vue        # Presentational — user info card
│   └── UserActivityFeed.vue   # Presentational — activity list
└── add/
    ├── UserAdd.vue            # Orchestrates add/create flow
    └── UserAddForm.vue        # Presentational — create form

<!-- app/components/user/detail/UserProfile.vue -->
<script setup lang="ts">
import type { User } from '~/shared/types/User'

const props = defineProps<{
  user: User
  isCurrentUser: boolean
}>()

const emit = defineEmits<{
  delete: []
}>()

const showConfirm = ref(false)

function confirmDelete(): void {
  showConfirm.value = true
}

function handleConfirm(): void {
  showConfirm.value = false
  emit('delete')
}
</script>

<template>
  <UCard>
    <template #header>
      <div class="flex items-center justify-between">
        <h1 class="text-xl font-bold">{{ user.name }}</h1>
        <UBadge :label="user.role" />
      </div>
    </template>

    <p class="text-gray-500">{{ user.email }}</p>

    <template #footer>
      <UButton
        v-if="isCurrentUser"
        color="red"
        variant="ghost"
        @click="confirmDelete"
      >
        Delete account
      </UButton>
    </template>

    <UModal v-model="showConfirm">
      <UCard>
        <p>Are you sure you want to delete your account?</p>
        <template #footer>
          <div class="flex gap-2">
            <UButton color="red" @click="handleConfirm">Confirm</UButton>
            <UButton variant="ghost" @click="showConfirm = false">Cancel</UButton>
          </div>
        </template>
      </UCard>
    </UModal>
  </UCard>
</template>

// app/stores/user.store.ts
import type { User } from '~/shared/types/User'

export const useUserStore = defineStore('user', () => {
  // State
  const currentUser = ref<User | null>(null)
  const users = ref<User[]>([])

  // Getters
  const isAuthenticated = computed(() => currentUser.value !== null)
  const isAdmin = computed(() =>
    currentUser.value?.roles.includes(UserRole.Admin) ?? false
  )

  // Actions
  function setCurrentUser(user: User | null): void {
    currentUser.value = user
  }

  function setUsers(list: User[]): void {
    users.value = list
  }

  function addUser(user: User): void {
    users.value.push(user)
  }

  function removeUser(id: string): void {
    users.value = users.value.filter(u => u.id !== id)
  }

  return {
    currentUser,
    users,
    isAuthenticated,
    isAdmin,
    setCurrentUser,
    setUsers,
    addUser,
    removeUser,
  }
})

<!-- app/layouts/default.vue -->
<template>
  <div class="flex flex-col min-h-screen">
    <AppHeader />
    <main class="flex-1">
      <slot />
    </main>
    <AppFooter />
  </div>
</template>

<!-- app/layouts/dashboard.vue -->
<template>
  <div class="flex">
    <DashboardSidebar />
    <main class="flex-1 p-6">
      <slot />
    </main>
  </div>
</template>

<!-- app/pages/dashboard/index.vue -->
<script setup lang="ts">
definePageMeta({ layout: 'dashboard' })
</script>

<script setup lang="ts">
definePageMeta({ layout: false })
</script>