Project Structure - PAiMo-io/PAiMo GitHub Wiki

🧱 Project Structure

This document provides an overview of the PAiMO monorepo file and folder structure to help new contributors understand where key functionality lives.

📂 Root Directory

PAiMo/
├── app/                     # App router: all pages and APIs
├── components/              # Shared UI components
├── lib/                     # Client-side helper utilities
├── models/                  # Mongoose schemas and models
├── public/                  # Static assets (e.g., images, favicon)
├── styles/                  # Global styles if any (e.g., Tailwind overrides)
├── utils/                   # Server-side utility functions (e.g., DB connection)
├── middleware.ts            # Middleware for auth, logging, etc.
├── next.config.js           # Next.js configuration
├── .env.local               # Environment variables
├── package.json             # Project dependencies and scripts
└── README.md                # Developer intro and setup instructions

🧭 Key Directories

app/

  • Uses Next.js App Router
  • Structure matches routing paths (e.g., app/profile/page.tsx → /profile)
  • Special folders:
    • app/api/ — API routes (e.g., auth, profile, password reset)
    • app/(auth)/ — Route groups for layout separation

components/

Reusable UI components:

  • Button.tsx, Input.tsx, PageSkeleton.tsx, Avatar.tsx, etc.
  • May use shadcn/ui or custom designs

models/

Mongoose schemas:

  • User.ts
  • Club.ts
  • Event.ts
  • Match.ts
  • PasswordReset.ts

utils/

Server-side helpers:

  • mongoose.ts — Database connection handler
  • auth.ts — Auth options for getServerSession
  • r2.ts — Upload/download logic for Cloudflare R2

lib/

Client-side utilities:

  • useApi.ts — Axios wrapper for API calls
  • validators.ts — (if any) Input validation

public/

  • Static files (e.g., /paimo_logo.png)
  • Accessible via / path (e.g., /paimo_logo.png)

📦 Backend API Highlights

  • /api/auth/ — NextAuth.js config & routes
  • /api/profile/ — Avatar upload, profile info
  • /api/request-password-reset — Generate and send token via email
  • /api/reset-password — Handle new password submission
  • /api/push/subscribe — Push notification subscription endpoint

🗃 Environment Variables

Defined in `.env.local`:
DB_URL=your-mongodb-uri
NEXTAUTH_SECRET=your-secret
NEXTAUTH_URL=http://localhost:3000
RESEND_API_KEY=your-resend-api-key
R2_ACCESS_KEY_ID=…
R2_SECRET_ACCESS_KEY=…

🛠 Scripts

Run development server:

npm run dev

Build and export:

npm run build && npm start