Stage 3 — Enterprise Architecture

Overview#

This stage establishes the folder structure every feature in the application will rely on. Rather than building business features first, we create a scalable structure so features have a consistent place to live from day one.

The architecture targets modern frontend applications — SaaS platforms, dashboards, admin panels, e-commerce, and other large-scale Next.js projects.

Objectives#

• Enterprise folder architecture
• Feature-based component organization
• Shared UI component library
• Layout system
• Provider architecture
• Configuration layer
• Environment management
• Utility layer
• Service layer
• Global state management foundation
• Shared hooks
• Centralized metadata
• Type-safe project foundation

Install Runtime Dependencies#

bun add axios zod clsx lucide-react next-themes class-variance-authority tailwind-merge react-hook-form zod-validation-error @hookform/resolvers

Folder Structure#

This structure is the contract for the project. Every later stage places files here — nowhere else.

src
│
├── app
│   ├── (auth)
│   ├── (protected)
│   ├── (public)
│   ├── api
│   ├── error.tsx
│   ├── favicon.ico
│   ├── layout.tsx
│   ├── loading.tsx
│   ├── not-found.tsx
│   ├── robots.txt
│   ├── sitemap.ts
│   └── page.tsx
│
├── assets
│   ├── fonts
│   ├── icons
│   ├── images
│   ├── logos
│   └── svg
│
├── components
│   ├── features
│   │   ├── auth
│   │   ├── dashboard
│   │   ├── navigation
│   │   └── profile
│   │
│   ├── layouts
│   │   ├── AppClientLayout
│   │   ├── Header
│   │   ├── Footer
│   │   ├── Theme
│   │   ├── AuthLayout
│   │   ├── ProtectedLayout
│   │   └── PublicLayout
│   │
│   ├── providers
│   │   ├── AuthProvider
│   │   └── ThemeProvider
│   │
│   └── ui
│       ├── buttons
│       │   └── Button.tsx
│       │
│       ├── inputs
│       │   ├── Input.tsx
│       │   ├── Checkbox.tsx
│       │   ├── Select.tsx
│       │   ├── PasswordInput.tsx
│       │   └── InputFactory.tsx
│       │
│       ├── links
│       │   └── Link.tsx
│       │
│       ├── svg
│       │   ├── EyeOpen.tsx
│       │   └── EyeClose.tsx
│       │
│       ├── images
│       │   ├── LucidIcon.tsx
│       │   ├── ImageComponent.tsx
│       │   └── NavigationLogo.tsx
│       │
│       └── shadcn
│           ├── avatar
│           ├── badge
│           ├── button
│           ├── card
│           ├── dialog
│           ├── dropdown
│           └── tabs
│
├── packages
│   ├── configs
│   ├── env
│   ├── hooks
│   ├── metadata
│   ├── forms
│   ├── schemas
│   ├── services
│   ├── store
│   └── utils
│
├── styles
│   ├── themes
|        ├── cyantrix.css
│   ├── utils
|        ├── app.css
|        ├── fonts.css
|        ├── theme.css
|        ├── animations.css
|        ├── typography.css
│   ├── ui
|        ├── input.css
|        ├── button.css
|        ├── navigation.css
│   ├── globals.css
│
└── types

Folder Responsibilities#

app#

Next.js App Router: route groups, pages, layouts, API routes, loading UI, error boundaries. No business logic here.

app
├── (auth)
├── (protected)
├── (public)
├── api
├── layout.tsx
└── page.tsx

assets#

Static assets: brand logos, custom icons, images, web fonts, SVG illustrations.

assets
├── fonts
├── icons
├── images
├── logos
└── svg

components#

Four categories, each with a distinct role.

components/features — feature-specific presentation components, scoped to one business domain, never reused globally.

features
├── auth
├── dashboard
├── navigation
└── profile

Examples: sign-in form, dashboard cards, user profile card, navigation menu.

components/layouts — reusable page structures that compose shared interface elements (auth pages, dashboard pages, marketing pages).

layouts
├── AppClientLayout
├── AuthLayout
├── ProtectedLayout
└── PublicLayout

components/providers — React providers consumed directly by UI components, exposing shared state through Context.

providers
├── AuthProvider
└── ThemeProvider

components/ui — reusable, business-logic-free UI building blocks.

ui
├── buttons
├── inputs
├── links
├── svg
├── images
└── shadcn

packages#

Reusable application logic — functionality, not presentation.

packages/configs — centralized app settings, navigation definitions, theme configuration.

configs
├── app.config.ts
├── navigation.config.ts
└── styles.config.ts

packages/env — environment variable parsing and validation, separated by client/server.

env
├── app.env.ts
├── auth.env.ts
└── client.env.ts

packages/hooks — generic, reusable custom hooks.

hooks
├── useBoolean.ts
├── useBreakpoints.ts
├── useDebounce.ts
├── useLocalStorage.ts
├── useMediaQuery.ts
└── useMounted.ts

packages/metadata — SEO metadata, Open Graph, Twitter cards.

metadata
├── app.metadata.ts
├── openGraph.ts
└── twitter.ts

packages/schemas — all Zod schemas: form validation, API validation, shared request models.

schemas
├── auth.schema.ts
├── common.schema.ts
└── user.schema.ts

packages/services — application services: Axios client, auth services, storage helpers. Business logic lives here, not in components.

services
├── api
├── auth
├── storage
└── index.ts

packages/store — global state management. Zustand is the default choice; this structure leaves room to expand if that changes.

store
├── context
├── reducers
├── slices
└── index.ts

packages/utils — framework-independent utility functions.

utils
├── cn.ts
├── cookies.ts
├── date.ts
├── format.ts
├── sanitize.ts
├── storage.ts
└── validators.ts

styles#

Global styling resources. navigation/ holds multiple navigation themes (classical corporate, premium cyber, transparent, sidebar, mobile).

styles
├── animations.css
├── globals.css
├── input.css
├── typography.css
├── ui.css
└── navigation.css

types#

Global TypeScript declaration files, shared across the app.

types
├── api.d.ts
├── app.d.ts
├── auth.d.ts
├── globals.d.ts
└── navigation.d.ts

Architecture Principles#

• Route-first — app defines routes and layouts; business logic stays out of it.
• Separation of concerns — UI, business logic, services, utilities, and configuration each own a clear responsibility.
• Feature-based organization — domain components live in components/features and evolve independently.
• Reusable UI — components/ui stays free of business logic.
• Centralized configuration — settings live in packages/configs, not scattered through the codebase.
• Type safety — shared types, schemas, and utilities are centralized to reduce duplication.
• Scalability — the structure holds from a small project to an enterprise application without a rewrite.

Stage Deliverables#

• ✅ Enterprise folder architecture
• ✅ Feature-based component organization
• ✅ Shared UI component library
• ✅ Multiple application layouts
• ✅ Configuration management
• ✅ Environment configuration
• ✅ Global providers
• ✅ Reusable hooks
• ✅ Service layer
• ✅ Utility layer
• ✅ Global state management foundation
• ✅ Type-safe project structure

Next Stage#

Continue to Stage 4 — Design System to define design tokens and the theme system.