├── src/             → Application source code
├── docs/            → Project documentation
├── config/          → Shared configuration (metadata, etc.)
├── scripts/         → Setup and maintenance scripts
├── drizzle/         → Generated SQL migration files
├── .github/         → GitHub workflows and templates
├── .husky/          → Git hooks (commitlint, etc.)
├── .storybook/      → Storybook configuration
├── public/          → Static assets

src/
├── app/             → Next.js App Router (pages, layouts, APIs)
├── components/      → Reusable UI components
├── db/              → Drizzle schema and runtime DB client
├── modules/         → Domain-level logic and components
├── hooks/           → Shared React hooks
├── lib/             → Core infrastructure
├── providers/       → App-level provider composition
├── services/        → HTTP/API client helpers
├── i18n/            → Internationalization setup
├── store/           → State management (optional)
├── styles/          → Global CSS
├── tests/           → Tests (unit, integration, e2e) + shared.ts
├── types/           → Shared TypeScript type definitions
├── utils/           → Shared utility functions

src/db/
├── index.ts         → Runtime Drizzle client
└── schema/          → Drizzle schema definitions

src/app/
├── (auth)/          → Auth pages (login, register)
│   ├── login/
│   │   └── page.tsx       → Login page
│   └── register/
│       └── page.tsx       → Registration page
├── api/
│   └── v1/
│       └── auth/          → Auth API routes
│           ├── login/route.ts
│           ├── register/route.ts
│           ├── me/route.ts
│           ├── logout/route.ts
│           ├── refresh/route.ts
│           └── mfa/verify/route.ts
├── dev/
│   └── flags/             → Feature flag toggle UI (dev only)
├── docs/                  → Documentation hub pages
│   ├── page.tsx           → Docs hub landing page
│   └── [...slug]/
│       └── page.tsx       → Individual doc article page
├── features/
│   └── page.tsx           → Features overview page
├── page.tsx               → Landing / home page
├── layout.tsx             → Root layout (fonts, providers, theme)
├── sitemap.ts             → Dynamic sitemap generation
├── robots.ts              → Robots.txt configuration
├── global-error.tsx       → Global error boundary
├── not-found.tsx          → 404 page
├── loading.tsx            → Loading state
└── error.tsx              → Error boundary

src/components/
├── common/          → Shared UI (Button, Input, ScrollRestoration, etc.)
├── docs/            → Documentation-specific components
│   └── DocsMarkdown.tsx   → Client-side markdown renderer (marked-based)
├── landing/         → Landing page components
│   ├── Navbar.tsx         → Auth-aware navigation bar with 8-locale dropdown
│   ├── Hero.tsx           → Hero section with tech icons
│   └── Features.tsx       → Features grid section
└── ui/              → Base UI primitives (Button, Input, etc.)

src/modules/
├── auth/            → Authentication module
│   ├── components/        → AuthForm, etc.
│   ├── hooks/             → useAuthForm, etc.
│   ├── services/          → Auth service (login, register, etc.)
│   ├── auth.schema.ts     → Zod validation schemas
│   └── auth.types.ts      → Auth-specific types
└── optional/
    └── auth/              → Custom auth provider adapter
        ├── custom-auth.provider.ts
        ├── custom-auth.adapter.ts
        └── custom-auth.types.ts

module-name/
├── components/     → React components for the module
├── hooks/          → React hooks for the module
├── services/       → Service/API integration layer
├── module.schema.ts    → Zod schemas
└── module.types.ts     → TypeScript types

src/lib/
├── auth/            → Authentication infrastructure
│   ├── session.ts         → Session token creation & verification
│   ├── session-guard.ts   → Permission checking middleware
│   ├── rbac.ts            → Role-based access control
│   ├── step-up.ts         → MFA step-up configuration
│   ├── step-up-guard.ts   → MFA step-up guard
│   ├── auth.provider.ts   → Auth provider abstraction
│   ├── better-auth.provider.ts  → Better Auth implementation
│   └── auth-audit.repository.ts → Audit log writes
├── config/          → Configuration system
│   ├── env.ts             → Environment variable schema (t3-env)
│   ├── validate.ts        → Runtime config validation
│   ├── runtime.ts         → API endpoint resolution
│   ├── url.ts             → Centralized origin/URL derivation (getLocalAppOrigin, getSiteOrigin)
│   ├── constants.ts       → App constants
│   ├── app-config.ts      → Parsed config object
│   ├── featureFlags.ts    → Feature flag definitions
│   ├── feature-registry.ts → Feature definitions (routes, permissions)
│   └── site-config.ts     → Site-wide configuration
├── docs/            → Documentation content helpers
│   └── content.ts         → Doc entries, slug resolution, GitHub links
├── observability/   → Logging and tracing
│   └── logger.ts          → Structured logging
├── security/        → Security utilities
│   ├── request-origin.ts  → Same-origin validation
│   ├── redirect.ts        → Safe redirects
│   └── rate-limit.ts      → Rate limiting
└── utils/           → General utilities
    ├── api-response.ts    → Standard API response helpers
    └── ...                → Other utilities

src/providers/
├── index.ts         → Provider composition (AppProviders)
├── auth.provider.ts       → Auth data prefetching
├── query.provider.ts      → TanStack React Query provider
├── theme.provider.ts      → Dark/light theme provider
└── toast.provider.ts      → Toast notification provider

QueryProvider → ThemeProvider → ToastProvider → AuthProvider → App

src/hooks/
└── useAuth.ts      → Auth hook (user, isAuthenticated, logout)

src/i18n/
├── config.ts        → i18n configuration
├── routing.ts       → Locale routing
├── navigation.ts    → Navigation helpers
├── request.ts       → Request-time locale detection
└── messages/
    ├── en.json      → English translations
    ├── bn.json      → Bangla translations
    ├── es.json      → Spanish translations
    ├── fr.json      → French translations
    ├── de.json      → German translations
    ├── hi.json      → Hindi translations
    ├── ja.json      → Japanese translations
    └── ar.json      → Arabic translations

src/tests/
├── shared.ts        → Shared test helpers (TEST_LOCAL_ORIGIN, testUrl)
├── unit/            → Unit tests (Vitest)
├── integration/     → Integration tests (Vitest)
│   ├── auth-api.test.ts    → Auth API integration tests
│   └── mode-guards.test.ts → Mode guard integration tests
└── e2e/             → End-to-end tests (Playwright)
    ├── home.spec.ts         → Landing + login/docs redirect behavior
    ├── i18n.spec.ts         → Locale toggle behavior checks
    └── sanity.check.spec.ts → Basic route/document sanity checks

docs/
├── architecture.md              → System architecture
├── auth-flow.md                 → Authentication flow
├── folder-structure.md          → This file
├── how-to-use.md                → Setup and daily workflow
├── workflows.md                 → GitHub Actions workflows
├── migrations/
│   └── package-manager.md       → Package manager migration guide
├── deployment/
│   └── cloud-providers.md       → Provider-specific deploy guides
├── guides/
│   ├── README.md                → Guides index
│   ├── contributing.md          → Contributor workflow and commit standards
│   ├── project-maintenance.md   → Ongoing maintainer playbook and troubleshooting
│   ├── deployment.md            → Deployment runbook
│   ├── github-setup-checklist.md → Repo hardening checklist
│   ├── project-maintenance.md   → Maintenance routines
│   └── release-automation.md    → Release Please guide
├── bn/                          → Bangla translations of docs
└── tools/                       → AI/agent config files

scripts/
├── setup.mjs        → First-time project setup
├── start.mjs        → Production server starter
├── seed.mjs         → Database seeding
├── db-reset.mjs     → Database reset
├── clean.mjs        → Project cleanup
└── check-docs.mjs   → Documentation consistency check