Skip to content

Folder Structure Overview

This document explains the purpose of each top-level folder and significant subfolders in the Constellation project.

Root Level

Configuration Files

  • bun.lock: Lock file for Bun package manager to ensure consistent dependencies.
  • bunfig.tml: Bun configuration file.
  • package.json: Project dependencies and scripts configuration.
  • package-lock.json: NPM lock file (maintained for compatibility).
  • next.config.mjs: Next.js framework configuration.
  • tailwind.config.ts: Tailwind CSS configuration and theme customization.
  • tsconfig.json: TypeScript compiler configuration.
  • postcss.config.mjs: PostCSS configuration for CSS processing.
  • eslint.config.mjs: ESLint configuration for code linting.
  • vitest.config.ts: Vitest test runner configuration.
  • vitest.setup.ts: Vitest global test setup and mocks.
  • components.json: Shadcn/ui components registry configuration.

Infrastructure Files

  • Dockerfile: Docker container configuration for production deployment.
  • compose.yml: Docker Compose configuration for local development environment.
  • .dockerignore: Files to exclude from Docker builds.
  • deployFront.sh: Frontend deployment automation script.
  • .env.local: Local environment variables (not tracked in git).

Documentation Files

  • README.md: Project overview and quick start guide.
  • CONTRIBUTING.md: Contribution guidelines and workflow.
  • QUALITY_ASSURANCE.md: Quality assurance standards and practices.

Top-Level Folders

  • src/: Main source code directory (detailed below).
  • public/: Static assets served directly by the web server.
  • docs/: Comprehensive project documentation.
  • registry/: Component registry for shadcn/ui integration.
  • .github/: GitHub workflows and CI/CD configuration.
  • .githooks/: Custom Git hooks for development workflow.

src/ Folder

The main source code directory, organized by feature and responsibility.

src/app/

Purpose: Next.js 13+ App Router pages and API routes.

The project uses the Next.js App Router architecture. Each folder corresponds to a route in the application. If a page.tsx file is found in a folder, it means that folder is a route endpoint. A layout.tsx file defines the layout wrapper for that route and its children.

Route Groups and Pages

  • (www)/: Public-facing marketing and authentication pages (route group, doesn't affect URL path)
  • about/: About page
  • about-us/: About us page
  • blog/: Blog landing page
  • login/: User login page
  • register/ & signup/: User registration pages
  • pricing/: Pricing information page
  • verify-student/: Student verification page

  • success/: Success confirmation page

  • (admin)/: Admin-only pages (route group)

  • admin/: Admin dashboard and management interface

  • dashboard/: Main application dashboard (authenticated users)

  • home/: Dashboard home view
  • elements/: Constellation elements management
  • graph/: Graph visualization view
  • maps/: Maps listing and management
  • map-editor/: Interactive map editor interface

  • manage/: General management interface

  • workspace/: Collaborative workspace for constellations

  • api/: Next.js API routes for backend functionality

  • checkout/: Payment checkout API endpoint
  • verify-student/: Student verification API endpoint

src/components/

Purpose: Reusable and modular UI components organized by feature or type.

  • admin/: Admin-specific UI components
  • common/: Shared components used across the application
  • context/: React Context providers and consumers for state management
  • dashboard/: Dashboard-specific components
  • editor/: Constellation editor components
  • forms/: Form components and input elements
  • graph/: Graph visualization and interaction components
  • mapEditor/: Map editor interface components
  • navigation/: Navigation bars, menus, and routing components
  • plate-ui/: Plate rich text editor UI components
  • tour/: Product tour and onboarding components
  • ui/: Base UI components (buttons, cards, dialogs, etc.) following shadcn/ui pattern

src/features/

Purpose: Feature-specific code modules that combine components, logic, and data handling.

  • homepage/: Landing page feature module
  • workspace/: Workspace feature implementation

src/hooks/

Purpose: Custom React hooks for reusable stateful logic.

Notable hooks include: - use-admin-ping.tsx: Admin authentication verification - use-auto-mention.tsx: Auto-mention functionality - use-copy-to-clipboard.tsx: Clipboard operations - use-custom-chat.tsx: Custom chat functionality - use-debounce.ts: Input debouncing - use-feature-announcement.tsx: Feature announcement system - use-is-admin.tsx: Admin role checking - use-is-touch-device.tsx: Touch device detection - use-language-change.tsx: Language switching - use-mobile.tsx: Mobile device detection - use-mounted.tsx: Component mount state - use-node-by-label.tsx: Graph node lookup - use-require-admin.tsx: Admin route protection - use-yjs.tsx: Yjs collaborative editing integration

src/i18n/

Purpose: Internationalization (i18n) configuration and utilities.

  • i18n.js: Main i18n configuration and language detection logic

src/lib/

Purpose: Utility libraries, helper functions, and shared logic.

  • api.ts: API client configuration and utilities
  • admin-api.ts: Admin-specific API utilities
  • auth.ts: Authentication utilities and helpers
  • filter-links.ts: Link filtering utilities
  • imageCache.ts: Image caching implementation
  • mapDemoStore.ts: Map demo state management
  • polarConfig.ts: Polar.sh payment integration configuration
  • uploadthing.ts: UploadThing file upload configuration
  • utils.ts: General utility functions
  • validation.ts: Input validation helpers

src/lib/schemas/

Purpose: Zod schema definitions for type-safe data validation.

  • admin.ts: Admin-related schemas
  • api.ts: API request/response schemas
  • collections.ts: Collection data schemas
  • constellations.ts: Constellation data schemas
  • memberships.ts: Membership and subscription schemas
  • users.ts: User data schemas

src/services/

Purpose: Business logic and external service integrations.

  • apiClient.ts: Main API client implementation
  • token.ts: Token management utilities

src/services/admin/

Purpose: Admin-specific service layer for backend operations.

  • analytics.ts: Analytics data retrieval and processing
  • auth.ts: Admin authentication logic
  • constellations.ts: Constellation management services
  • dashboard.ts: Dashboard data aggregation
  • newsletter.ts: Newsletter management
  • permissions.ts: Permission checking and enforcement
  • users.ts: User management services

src/test/

Purpose: Testing utilities and mock data.

  • mocks/: Mock implementations for testing

src/types/

Purpose: TypeScript type definitions and interfaces.

  • chat.ts: Chat-related type definitions
  • data.ts: General data type definitions

public/ Folder

Purpose: Static assets served directly by Next.js without processing.

  • fonts/: Web font files
  • images/: Image assets
  • team/: Team member photos
  • locales/: Translation files for i18n
  • en/: English translations
  • fr/: French translations
  • logos/: Logo assets
  • brand/: Brand logos and variations
  • showcase/: Showcase images and demos
  • tiles/: Map tile images organized by zoom level (0-5)

docs/ Folder

Purpose: Comprehensive project documentation organized by topic.

Main Documentation Files

  • INDEX.md: Documentation index and navigation
  • 00-OVERVIEW.md: High-level project overview
  • 00-CAMPAIGN_SUMMARY.md: Marketing campaign summary
  • 01-PROJECT_OVERVIEW.md: Detailed project description
  • 02-SETUP_GUIDE.md: Development environment setup
  • 03-QUICK_START.md: Quick start guide for new developers
  • 04-ARCHITECTURE.md: System architecture documentation
  • 05-CODE_STYLE_GUIDE.md: Code style standards
  • 06-COMPONENTS.md: Component documentation
  • 07-HOOKS.md: Custom hooks documentation
  • 08-SERVICES.md: Service layer documentation
  • 09-STATE_MANAGEMENT.md: State management patterns
  • 10-EDITOR.md: Editor implementation details
  • 14-TESTING.md: Testing strategy and guidelines
  • 17-STYLING.md: Styling approach and guidelines
  • 19-DEPLOYMENT.md: Deployment procedures
  • 20-PERFORMANCE.md: Performance optimization guide
  • 23-TROUBLESHOOTING.md: Common issues and solutions
  • 24-FAQ.md: Frequently asked questions
  • 25-CONTRIBUTING.md: Contribution workflow

Testing Documentation

  • TESTING.md: Main testing documentation
  • TESTING_COMPLETE.md: Complete testing guide
  • TESTING_SUMMARY.md: Testing summary
  • QUICK_TEST_REFERENCE.md: Quick testing reference
  • TEST_TEMPLATE.md: Test file template

Zod Validation Documentation

  • ZOD_API_VALIDATION.md: API validation with Zod
  • ZOD_QUICKSTART.md: Quick start guide for Zod
  • ZOD_SETUP_COMPLETE.md: Zod setup completion guide

docs/CONTRIBUTING/

Purpose: Detailed contributing guidelines.

  • CODING_STANDARDS.md: Code quality and standards
  • FOLDER_STRUCTURE.md: This file - project structure overview
  • TECHNICAL_STACK.md: Technology stack documentation

Other Important Folders

.github/

Purpose: GitHub-specific configuration.

  • workflows/: GitHub Actions CI/CD workflow definitions

.githooks/

Purpose: Custom Git hooks for automated checks and tasks during development.

registry/

Purpose: Component registry for shadcn/ui component integration.

  • default/: Default component registry

File Naming Conventions

  • Page files: page.tsx - Next.js route endpoints
  • Layout files: layout.tsx - Route layout wrappers
  • Component files: PascalCase.tsx - React components
  • Utility files: kebab-case.ts - Utility functions
  • Hook files: use-hook-name.tsx - Custom React hooks
  • Test files: *.test.ts or *.test.tsx - Test files (co-located with source)
  • Type files: kebab-case.ts - TypeScript types and interfaces
  • Schema files: kebab-case.ts - Zod validation schemas