Skip to content

🏗️ 2. System Architecture

TaskNexus is built on a modern Next.js 15 architecture, leveraging the App Router for efficient data fetching and server-side logic.

🧱 Technology Stack

Component Technology Description
Frontend Framework Next.js 15 React framework with App Router & Server Actions.
Language TypeScript Statically typed JavaScript for safety.
Styling Tailwind CSS Utility-first CSS framework.
Database ORM Prisma Type-safe database client.
Database PostgreSQL Relational database (schema managed by Prisma).
AI Integration Google Generative AI SDK Interface for Gemini models.

📂 Folder Structure Deep Dive

Understanding the project layout is crucial for navigation.

TaskNexus/
├── .env                # Environment variables (Git-ignored)
├── package.json        # Dependencies and scripts
├── prisma/
│   └── schema.prisma   # Database schema definition
├── public/             # Static assets (images, icons)
├── src/
│   ├── app/            # Application Routes (App Router)
│   │   ├── (auth)/     # Route group for auth pages (login/signup)
│   │   ├── (dashboard)/# Route group for protected pages with sidebar
│   │   ├── actions/    # SERVER ACTIONS (Business Logic)
│   │   ├── api/        # API Routes (for external webhooks)
│   │   ├── layout.tsx  # Root layout
│   │   └── page.tsx    # Landing page
│   ├── components/     # Reusable UI components
│   │   ├── ui/         # Generic UI elements (Buttons, Cards)
│   │   └── ...         # Feature-specific components
│   └── lib/            # Shared Utilities & Libraries
│       ├── ai.ts       # AI Service Wrapper
│       ├── auth.ts     # Authentication Helpers
│       ├── db.ts       # Prisma Client Singleton
│       └── violations.ts # Governance Logic

Key Architectural Concepts

1. Server Actions as Backend

Instead of a traditional REST API (e.g., pages/api/...), TaskNexus uses Server Actions. These are async functions that run on the server but can be called directly from frontend components.

  • Location: src/app/actions/
  • Benefit: Type safety from frontend to backend, no need to manually serialize JSON.
  • Security: Always validate inputs and check authentication (requireUser()) inside every server action.

2. Route Groups (folder)

We use route groups to organize pages without affecting the URL structure.

  • (dashboard): Wraps all dashboard pages with a common Sidebar Layout.
    • URL: /dashboard, /projects, etc. (NOT /dashboard/projects).
  • This allows us to persist the Sidebar state across navigation.

3. Singleton Database Client

To prevent exhausting database connections during hot-reloading in development, we use a singleton pattern for Prisma.

  • File: src/lib/db.ts
  • It attaches the PrismaClient instance to the globalThis object.

Next: Core Systems ➡️