Carlos Eduardo Gatti Ferreira

Monorepo Structure

This document explains how the codebase is organized, why it’s structured this way, and how to navigate and extend it.

Overview

This is a monorepo — a single repository containing multiple applications and shared code. All code lives in one place, making it easier to:

• Share code between products
• Maintain consistent patterns
• Deploy everything together
• Reduce duplication

---

Root Directory Structure

carlosgatti.com/
├── app/                    # Next.js App Router (Discart-me, QRACK)
├── pages/                  # Next.js Pages Router (Personal website)
├── src/                    # Shared source code
├── components/             # Root-level shared components
├── docs/                   # Documentation
├── public/                 # Static assets
├── styles/                 # Global styles
├── scripts/                # Build and utility scripts
├── constants/              # Shared constants
├── types/                  # Root-level TypeScript types
├── util/                   # Utility functions
├── package.json            # Dependencies and scripts
├── tsconfig.json           # TypeScript configuration
├── tailwind.config.js      # Tailwind CSS configuration
├── next.config.mjs         # Next.js configuration
└── README.md               # This file's parent

---

/app — App Router Applications

Purpose: Next.js 13+ App Router applications

Structure:

app/
├── discart-me/            # Discart-me marketplace app
│   ├── layout.tsx         # App-wide layout with auth provider
│   ├── page.tsx           # Landing page
│   ├── dashboard/
│   ├── items/
│   └── README.md          # App-specific documentation
├── qrack/                 # QRACK inventory app
│   ├── layout.tsx         # App-wide layout with auth provider
│   ├── page.tsx           # Landing page
│   ├── containers/
│   ├── scanner/
│   └── README.md          # App-specific documentation
└── layout.tsx             # Root layout (wraps all apps)

Key Points:

• Each app has its own folder with routes as subdirectories
• Each app has a layout.tsx that wraps routes with app-specific providers
• Apps are completely independent in routing but can share code from /src
• Route protection is handled at the layout or page level

Conventions:

• App names are lowercase, hyphenated (e.g., discart-me, qrack)
• Each app has a README.md explaining its purpose and routes
• Apps should not directly import from other apps

---

/pages — Pages Router (Legacy)

Purpose: Next.js Pages Router for the personal website

Structure:

pages/
├── _app.tsx               # App wrapper (providers, global styles)
├── _document.tsx          # HTML document customization
├── index.tsx              # Home page
├── about.tsx              # About page
├── blogs/                 # Blog posts (MDX)
│   ├── index.tsx          # Blog listing
│   └── {slug}/            # Individual blog posts
├── projects.tsx           # Projects showcase
└── api/                   # API routes
    ├── send-email.tsx     # Email sending endpoint
    └── generate-resume.ts # Resume PDF generation

Key Points:

• Used for the personal website (portfolio, blog)
• Will gradually migrate to App Router in the future
• API routes remain in /pages/api even after migration

Conventions:

• File-based routing (file name = route path)
• _app.tsx for global providers and styles
• _document.tsx for HTML structure customization

---

/src — Shared Source Code

Purpose: Reusable code shared across all applications

Structure:

src/
├── components/            # Shared React components
│   ├── discart-me/       # Discart-me specific components
│   ├── qrack/            # QRACK specific components
│   ├── comments/         # Comments feature components
│   └── ratings/          # Ratings feature components
├── features/             # Feature modules
│   ├── auth/             # Authentication feature
│   │   ├── AuthProvider.tsx
│   │   ├── useAuth.ts
│   │   ├── providers/
│   │   └── hooks/
│   ├── discart-me/       # Discart-me features
│   │   └── hooks/
│   └── qrack/            # QRACK features
│       ├── components/
│       └── hooks/
├── lib/                  # Libraries and utilities
│   ├── api/              # API clients
│   │   └── core/         # Core API utilities
│   ├── image/            # Image processing library
│   ├── qrackApi.ts       # QRACK GraphQL client
│   ├── discartMeApi.ts   # Discart-me REST client
│   ├── boxhubApi.ts      # BoxHub GraphQL client
│   ├── upload.ts         # File upload helpers
│   └── utils.ts          # General utilities
├── hooks/                # Shared React hooks
│   ├── useComments.ts
│   ├── useRatings.ts
│   ├── useDebounce.ts
│   └── ...
├── context/              # React Context providers
│   ├── DiscartAuthContext.tsx
│   ├── QrackAuthContext.tsx
│   └── BoxHubAuthContext.tsx
├── graphql/              # GraphQL queries and mutations
│   ├── queries/
│   └── mutations/
├── types/                # Shared TypeScript types
└── constants/            # Shared constants

Key Points:

• Code here is meant to be reused across applications
• Domain-specific code lives in domain folders (e.g., components/discart-me/)
• Generic code lives at the root level (e.g., lib/image/)
• Features follow a consistent structure (components, hooks, types)

Conventions:

• Domain folders (discart-me/, qrack/) contain domain-specific code
• Generic folders contain reusable code
• All TypeScript files use .ts or .tsx
• Feature modules should be self-contained (components, hooks, types together)

---

/components — Root-Level Components

Purpose: High-level layout and shared UI components

Structure:

components/
├── ui/                   # Generic UI primitives
│   ├── Button.tsx
│   ├── Input.tsx
│   ├── Modal.tsx
│   ├── Loading.tsx
│   └── index.ts
├── Navbar/               # Navigation components
├── Footer.tsx            # Site footer
├── Hero.tsx              # Hero sections
└── ...

Key Points:

• UI components in /components/ui are generic and domain-agnostic
• Layout components (Navbar, Footer) are shared across apps
• These components are used by both App Router and Pages Router apps

Conventions:

• UI primitives must be generic (no business logic)
• Components use forwardRef when appropriate
• Export from index.ts for cleaner imports

---

/docs — Documentation

Purpose: All project documentation

Structure:

docs/
├── architecture.md           # System architecture
├── monorepo-structure.md     # This file
├── tech-stack.md             # Technologies used
├── conventions.md            # Coding conventions
├── decisions.md              # Architectural decisions
├── adr/                      # Architectural Decision Records
│   └── ADR-001-frontend-foundation-phase.md
├── analysis/                 # Analysis documents
│   └── IMAGE_UPLOAD_AUDIT.md
├── refactors/                # Refactoring documentation
│   ├── discart-me-image-processing.md
│   └── qrack-create-container.md
└── ui/                       # UI documentation
    └── UI_BASE_GUIDELINES.md

Conventions:

• Documentation lives close to code (app-specific docs in /app/{app}/docs)
• Markdown files are Docusaurus-compatible (for future migration)
• ADRs follow a consistent format (Context, Decision, Consequences)

---

/public — Static Assets

Purpose: Files served statically (images, fonts, etc.)

Structure:

public/
├── blogs/                 # Blog images
├── discartme/             # Discart-me assets
├── qrack/                 # QRACK assets
├── boxhub/                # BoxHub assets
└── images/                # General images

Conventions:

• Organize by feature/app
• Use descriptive filenames
• Optimize images before committing

---

Adding New Applications

Step 1: Create App Folder

app/
└── my-new-app/
    ├── layout.tsx
    ├── page.tsx
    └── README.md

Step 2: Add Layout with Providers

// app/my-new-app/layout.tsx
import { MyAppProvider } from '@/src/context/MyAppContext';

export default function MyAppLayout({ children }) {
  return (
    <MyAppProvider>
      {children}
    </MyAppProvider>
  );
}

Step 3: Create Domain-Specific Code

src/
├── components/
│   └── my-new-app/       # App-specific components
└── features/
    └── my-new-app/       # App-specific features

Step 4: Document

Create app/my-new-app/README.md explaining:

• What the app does
• Routes and navigation
• Authentication requirements
• Key features

---

Adding New Packages/Features

Feature Module Structure

src/features/
└── my-feature/
    ├── components/        # Feature-specific UI
    ├── hooks/            # Feature-specific logic
    ├── types.ts          # Feature types
    └── README.md         # Feature documentation (if complex)

Shared Library Structure

src/lib/
└── my-library/
    ├── index.ts          # Public API
    ├── core.ts           # Core functionality
    ├── utils.ts          # Utilities
    └── types.ts          # Types

Guidelines:

• Keep features self-contained
• Export clean public APIs
• Document usage in code comments
• Add to /docs if architectural decisions are involved

---

Import Paths

Path Aliases

Configured in tsconfig.json:

{
  "paths": {
    "@/*": ["./*"],              // Root imports
    "@/src/*": ["./src/*"],      // Source code imports
    "@/components/*": ["./components/*"]
  }
}

Import Examples

// From root
import { Button } from '@/components/ui';

// From src
import { processImage } from '@/src/lib/image';
import { useAuth } from '@/src/features/auth/useAuth';

// Relative (within same feature)
import { MyComponent } from './components/MyComponent';

Conventions:

• Use @/ for root-level imports
• Use @/src/ for source code imports
• Use relative paths for imports within the same feature/component

---

File Naming Conventions

Components

• PascalCase: Button.tsx, ItemCard.tsx
• Descriptive: ItemForm.tsx not Form.tsx
• Suffixes: Use suffixes for variants (Button.tsx, ButtonIcon.tsx)

Utilities

• camelCase: utils.ts, processImage.ts
• Descriptive: validateImageFile.ts not validate.ts

Types

• camelCase with .types.ts suffix: image.types.ts, auth.types.ts
• Or inline types in component files

Hooks

• camelCase with use prefix: useAuth.ts, useImageProcessor.ts

---

Where Documentation Lives

Global Documentation

• /docs — Architecture, conventions, decisions
• README.md — Repository overview

App Documentation

• /app/{app}/README.md — App overview
• /app/{app}/docs/ — App-specific docs (optional)

Feature Documentation

• Inline code comments for usage
• /docs/refactors/ for refactoring documentation
• /docs/05-adr/ for architectural decisions

---

Future Considerations

Potential Reorganization

As the monorepo grows, consider:

1. Workspace Packages — Move shared code to packages/ (if using npm workspaces)
2. App Extraction — Extract apps to separate repos if they become too independent
3. Turborepo — Add build system for parallel builds and caching

Current Approach

For now, the flat structure works well because:

• Code is easy to find
• No build complexity
• Clear separation via folders
• TypeScript path aliases simplify imports

---

Related Documentation

• Architecture — System design
• Tech Stack — Technologies used
• Conventions — Coding standards
• Decisions — Architectural decisions