Project Structure

Understanding HiveForge's monorepo architecture and file organization.

Overview

HiveForge uses a Turborepo monorepo structure to organize code into apps and shared packages.

hiveforge/
├── apps/                    # Applications
│   ├── web/                # Next.js frontend
│   └── api/                # FastAPI backend
├── packages/               # Shared packages
│   ├── ui/                 # Shared UI components
│   ├── config/             # Shared configuration
│   ├── types/              # TypeScript types
│   └── pyshared/           # Python shared utilities
├── docs/                   # Documentation site (Nextra)
├── infra/                  # Infrastructure configs
├── scripts/                # Development scripts
├── supabase/              # Supabase migrations and config
├── .github/               # GitHub Actions workflows
└── turbo.json             # Turborepo configuration

Applications

Frontend (`apps/web/`)

Next.js 14 application with App Router.

apps/web/
├── src/
│   ├── app/                    # App Router pages
│   │   ├── (auth)/            # Auth route group
│   │   │   ├── login/
│   │   │   └── signup/
│   │   ├── (dashboard)/       # Protected routes
│   │   │   ├── dashboard/
│   │   │   ├── settings/
│   │   │   └── billing/
│   │   ├── (marketing)/       # Public pages
│   │   │   ├── page.tsx       # Homepage
│   │   │   ├── pricing/
│   │   │   └── features/
│   │   ├── api/               # API routes
│   │   │   ├── auth/
│   │   │   └── webhooks/
│   │   ├── layout.tsx         # Root layout
│   │   └── globals.css        # Global styles
│   ├── components/            # React components
│   │   ├── ui/               # Base UI components
│   │   ├── forms/            # Form components
│   │   ├── layouts/          # Layout components
│   │   └── features/         # Feature-specific components
│   ├── lib/                   # Utilities and helpers
│   │   ├── supabase/         # Supabase client
│   │   ├── stripe/           # Stripe utilities
│   │   ├── api/              # API client
│   │   └── utils.ts          # General utilities
│   ├── hooks/                 # React hooks
│   │   ├── useAuth.ts
│   │   ├── useOrganization.ts
│   │   └── usePermissions.ts
│   ├── types/                 # TypeScript types
│   ├── styles/                # Additional styles
│   └── middleware.ts          # Next.js middleware
├── public/                    # Static assets
│   ├── images/
│   └── fonts/
├── emails/                    # React Email templates
│   ├── welcome.tsx
│   ├── invitation.tsx
│   └── receipt.tsx
├── tests/                     # Tests
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── next.config.js            # Next.js configuration
├── tailwind.config.ts        # Tailwind CSS config
├── tsconfig.json             # TypeScript config
└── package.json              # Dependencies

Backend (`apps/api/`)

FastAPI application with async Python.

apps/api/
├── app/
│   ├── routers/               # API route handlers
│   │   ├── auth.py           # Authentication
│   │   ├── users.py          # User management
│   │   ├── organizations.py  # Organization management
│   │   ├── billing.py        # Stripe integration
│   │   ├── ai.py             # AI endpoints
│   │   ├── platform.py       # Platform admin
│   │   ├── templates.py      # Template management
│   │   └── health.py         # Health checks
│   ├── services/              # Business logic
│   │   ├── auth_service.py
│   │   ├── organization_service.py
│   │   ├── billing_service.py
│   │   ├── email_service.py
│   │   └── ai_service.py
│   ├── models/                # Database models
│   │   ├── user.py
│   │   ├── organization.py
│   │   ├── subscription.py
│   │   └── api_key.py
│   ├── schemas/               # Pydantic schemas
│   │   ├── user.py
│   │   ├── organization.py
│   │   └── billing.py
│   ├── core/                  # Core utilities
│   │   ├── config.py         # Settings
│   │   ├── security.py       # Auth utilities
│   │   ├── database.py       # DB connection
│   │   └── dependencies.py   # FastAPI dependencies
│   ├── middleware/            # Middleware
│   │   ├── auth.py
│   │   ├── rate_limit.py
│   │   └── logging.py
│   └── main.py               # FastAPI app
├── tests/                     # Tests
│   ├── test_auth.py
│   ├── test_organizations.py
│   └── conftest.py
├── alembic/                   # Database migrations (if using)
├── scripts/                   # Utility scripts
├── requirements.txt           # Python dependencies
├── Dockerfile                # Docker configuration
└── pyproject.toml            # Python project config

Shared Packages

UI Package (`packages/ui/`)

Shared React components used across applications.

packages/ui/
├── src/
│   ├── components/
│   │   ├── Button/
│   │   │   ├── Button.tsx
│   │   │   ├── Button.test.tsx
│   │   │   └── index.ts
│   │   ├── Input/
│   │   ├── Card/
│   │   ├── Modal/
│   │   ├── Table/
│   │   └── index.ts          # Export all components
│   ├── hooks/                 # Shared hooks
│   ├── utils/                 # Utilities
│   └── index.ts              # Package entry
├── tsconfig.json
└── package.json

Config Package (`packages/config/`)

Shared configuration for ESLint, TypeScript, Tailwind.

packages/config/
├── eslint/
│   ├── next.js               # ESLint config for Next.js
│   └── react.js              # ESLint config for React
├── typescript/
│   ├── base.json             # Base TypeScript config
│   ├── nextjs.json           # Next.js specific
│   └── react.json            # React specific
├── tailwind/
│   └── base.js               # Base Tailwind config
└── package.json

Types Package (`packages/types/`)

Shared TypeScript types and interfaces.

packages/types/
├── src/
│   ├── user.ts               # User types
│   ├── organization.ts       # Organization types
│   ├── billing.ts            # Billing types
│   ├── api.ts                # API response types
│   └── index.ts              # Export all types
├── tsconfig.json
└── package.json

Python Shared (`packages/pyshared/`)

Shared Python utilities and types.

packages/pyshared/
├── hiveforge_shared/
│   ├── __init__.py
│   ├── constants.py          # Shared constants
│   ├── utils.py              # Utilities
│   └── types.py              # Type definitions
├── setup.py
└── pyproject.toml

Infrastructure

Supabase (`supabase/`)

Database migrations and configuration.

supabase/
├── migrations/                # SQL migrations
│   ├── 20240101000000_initial_schema.sql
│   ├── 20240102000000_add_organizations.sql
│   └── 20240103000000_add_rbac.sql
├── seed.sql                   # Seed data
├── config.toml               # Supabase config
└── functions/                # Edge functions (optional)

Infrastructure Config (`infra/`)

Deployment configurations and docs.

infra/
├── docker/
│   ├── Dockerfile.web
│   └── Dockerfile.api
├── railway/
│   └── railway.toml
├── netlify/
│   └── netlify.toml
└── docs/
    ├── DEPLOYMENT.md
    ├── ENVIRONMENT_VARIABLES.md
    └── TROUBLESHOOTING.md

CI/CD (`.github/`)

GitHub Actions workflows.

.github/
├── workflows/
│   ├── ci.yml                # Continuous integration
│   ├── deploy-web.yml        # Deploy frontend
│   ├── deploy-api.yml        # Deploy backend
│   ├── test.yml              # Run tests
│   └── release.yml           # Create releases
├── ISSUE_TEMPLATE/
└── PULL_REQUEST_TEMPLATE.md

Key Files

Root Configuration

hiveforge/
├── .env.example              # Environment variables template
├── .env                      # Local environment (not committed)
├── .gitignore               # Git ignore rules
├── .prettierrc              # Prettier config
├── .eslintrc.js             # ESLint config
├── turbo.json               # Turborepo config
├── pnpm-workspace.yaml      # pnpm workspace config
├── package.json             # Root package.json
├── tsconfig.json            # Root TypeScript config
├── README.md                # Project README
└── LICENSE                  # License file

Turborepo Config (`turbo.json`)

{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "outputs": []
    }
  }
}

File Naming Conventions

Frontend

Components: PascalCase (Button.tsx, UserProfile.tsx)
Pages: kebab-case directories with page.tsx
API Routes: kebab-case directories with route.ts
Utilities: camelCase (formatDate.ts, apiClient.ts)
Hooks: camelCase with use prefix (useAuth.ts)
Types: PascalCase (User.ts, Organization.ts)

Backend

Files: snake_case (user_service.py, auth_router.py)
Classes: PascalCase (UserService, OrganizationModel)
Functions: snake_case (get_user, create_organization)
Constants: UPPER_SNAKE_CASE (MAX_RETRIES, DEFAULT_TIMEOUT)

Import Aliases

Frontend (`apps/web/tsconfig.json`)

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/lib/*": ["./src/lib/*"],
      "@/hooks/*": ["./src/hooks/*"],
      "@/types/*": ["./src/types/*"]
    }
  }
}

Usage:

import { Button } from '@/components/ui/Button'
import { useAuth } from '@/hooks/useAuth'
import { apiClient } from '@/lib/api'

Backend (Python)

# Use absolute imports
from app.services.auth import AuthService
from app.models.user import User
from app.core.config import settings

Environment Files

.env                    # Local development (not committed)
.env.example           # Template with all variables
.env.local             # Local overrides
.env.production        # Production variables (not committed)
.env.test              # Test environment

Best Practices

Directory Organization

Group by feature: Keep related files together
Shared code in packages: Don't duplicate code
Clear naming: Use descriptive names
Consistent structure: Follow established patterns

Component Organization

// Component file structure
import { dependencies }
 
interface Props { }
 
export function Component({ props }: Props) {
  // Hooks
  const [state, setState] = useState()
 
  // Effects
  useEffect(() => { })
 
  // Handlers
  function handleClick() { }
 
  // Render
  return <div>...</div>
}

File Size

Components: < 200 lines (split if larger)
Utilities: < 100 lines per function
Services: One responsibility per file
Routes: Thin controllers, business logic in services

Next Steps

Common Workflows Overview