Skip to content

PROJECT_STRUCTURE.md

Latest commit

 

History

History
87 lines (53 loc) · 4.59 KB

PROJECT_STRUCTURE.md

File metadata and controls

87 lines (53 loc) · 4.59 KB

Project Spark Architecture & Folder Structure

This document provides an overview of the folder structure and architectural patterns used in the Project Spark application. The project is built with Next.js (App Router), TypeScript, Drizzle ORM, and Tailwind CSS.

High-Level Overview

The application follows a feature-first organization within a standard Next.js App Router framework. The core logic is encapsulated in server-actions, with the UI being built through a combination of server components and interactive client components.

Root Directory

  • .github/: Contains CI/CD workflow configurations for deploying the application to Azure.
  • .husky/: Holds Git hooks scripts (e.g., pre-commit, pre-push) to enforce code quality and run checks before committing or pushing code.
  • public/: Stores all static assets that are publicly accessible, such as images, logos, and fonts.
  • src/: The main source code for the application. See the detailed breakdown below.
  • drizzle.config.ts: Configuration file for Drizzle ORM, used for database migrations and schema management.
  • next.config.mjs: Configuration file for the Next.js framework.
  • package.json: Defines project metadata, dependencies, and scripts.
  • tsconfig.json: TypeScript compiler options for the project.

src Directory Deep Dive

This is where the core application logic resides.

src/app/

This directory is the heart of the Next.js application, using the App Router paradigm.

  • Route Groups (authentication), (dashboard), (admin): These folders are Next.js Route Groups. They are used to organize routes and apply specific layouts to sections of the app without affecting the URL path. For example, all routes within (dashboard) will share the layout defined in (dashboard)/layout.tsx.
  • api/: Contains API route handlers for creating backend endpoints.
  • layout.tsx: The root layout for the entire application.
  • globals.css: Global stylesheets applied to the entire application.

src/components/

Contains all reusable React components.

  • ui/: Generic, low-level UI components (e.g., Button, Input, Card). These are the building blocks of the application's design system.
  • Feature-specific folders (e.g., HomePageComponents, Dashboard, Communities): Components that are specific to a particular feature or page are organized into their own folders.

src/db/

Manages the database connection and schema.

  • schema.ts: Defines the database schema using Drizzle ORM. This is the single source of truth for the database structure.
  • migrations/: Contains SQL migration files automatically generated by Drizzle to version control the database schema.
  • data-access/: Likely contains Data Access Objects (DAOs) or repository patterns for querying the database.
  • seeds/: Scripts for populating the database with initial or test data.

src/hooks/

Contains custom React hooks for encapsulating and reusing client-side stateful logic. Examples include useAuthUser for accessing user data or useBreakpoint for responsive design logic.

src/lib/

A collection of library code, utility functions, and configurations.

  • utils.ts: General-purpose utility functions.
  • permissions.config.ts: Configuration file defining user roles and permissions, used by the permission checking system.

src/server-actions/

This is a critical directory containing the core business logic of the application, implemented as Next.js Server Actions.

  • Each sub-folder (e.g., User, Post, Community, events) corresponds to a specific feature or domain.
  • These server-side functions can be called directly from client or server components, simplifying data mutations and backend communication.

src/services/

For logic that interacts with external services or APIs.

  • auth/: Authentication-related services (e.g., connecting to an auth provider).
  • realtime/: Services for handling real-time communication (e.g., WebSockets).
  • storage/: Services for interacting with a file storage provider (e.g., Azure Blob Storage, AWS S3).

src/store/

Contains client-side state management logic, likely using a library like Zustand or Redux. Each sub-folder represents a "slice" or "store" for a specific feature (e.g., user, community, chat).

src/types/

Holds shared TypeScript type definitions and interfaces used throughout the application.

src/utils/

Contains utility functions, often separated into clientHelpers.ts and serverHelpers.ts for code that should only run in a specific environment.