Project Structure: A Guide to Layered Architecture
Clean Separation of Concerns
Talon Core follows a strict Layered Architecture to prevent the "spaghetti code" issues common in full-stack frameworks. Code is organized not just by file type, but by responsibility—ensuring scalability for enterprise-grade applications.
Directory Overview
The codebase is divided into four main domains:
app/: The Nuxt 4 Frontend Client (UI, State, Routing)server/: The Nitro Backend Server (API, Business Logic, DB Access)shared/: Universal logic used by both Client and Server (Types, Validation)design-system/: Design tokens and theme generation scripts
bash
talon-core/
├── app/ # Frontend (Vue 3 + Nuxt 4)
├── server/ # Backend (Nitro + Drizzle ORM)
├── shared/ # Shared Code (Zod Schemas, Types)
├── design-system/ # Design Tokens (Primitive/Semantic)
├── public/ # Static Assets (Favicon, Robots.txt)
└── tests/ # Testing (Playwright, Vitest)
1. Server Layer (/server)
The backend logic is structured into three distinct layers. This is the most critical part of Talon Core's architecture.
| Directory | Layer | Role & Responsibility |
|---|---|---|
api/ | Controller | Handles HTTP requests, validates input, calls Services. |
services/ | Service | Core business logic (auth.service.ts, payment.service.ts). |
repositories/ | Repository | Direct database access via Drizzle ORM. |
Key Files
db/schemas/: Database table definitions (Drizzle ORM).utils/: Helper functions for Auth (OAuth), Email, and Payment integrations.
2. Application Layer (/app)
The frontend follows standard Nuxt 4 conventions with additional structure for scalability.
| Directory | Purpose |
|---|---|
components/ | Atomic Design: base/ (Atoms), composite/ (Molecules), modals/ (Organisms). |
composables/ | Business Logic: Hooks for API calls (useApi, useAuth) and UI state. |
pages/ | File-based Routing: Defines the URL structure of the application. |
stores/ | Global State: Pinia stores for cross-component data (e.g., toast, dialog). |
assets/scss/ | Styling: Global SCSS, including auto-generated design tokens. |
3. Shared Layer (/shared)
To ensure Type Safety, data structures are defined in one place and imported by both frontend and backend.
schemas/: Zod validation schemas (e.g.,auth.ts,board.ts). Used by API for validation and Frontend for forms.types/: TypeScript interfaces and DTOs.constants/: Shared constants (e.g.,USER_ROLE_ENUM).
4. Design System (/design-system)
Talon Core decouples design values from code.
tokens/: JSON/JS files defining color palettes and spacing.generate-tokens.js: A build script that compiles tokens into SCSS variables and CSS Custom Properties.