Carlos Eduardo Gatti Ferreira

Architecture Overview

This document describes the high-level architecture of the frontend monorepo, how applications interact, and the design patterns used throughout the codebase.

System Overview

This is a monorepo containing multiple Next.js applications that share code, components, and infrastructure while maintaining clear boundaries for independent operation.

Core Principles

1. Code Reuse — Share logic, components, and utilities across products
2. Clear Boundaries — Each app is independent but can leverage shared infrastructure
3. Consistent Patterns — Same patterns and conventions across all applications
4. Progressive Enhancement — New apps benefit from shared improvements

---

Application Architecture

High-Level Diagram

┌─────────────────────────────────────────────────────────┐
│                   Frontend Monorepo                      │
├─────────────────────────────────────────────────────────┤
│                                                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ Personal     │  │ Discart-me   │  │ QRACK        │  │
│  │ Website      │  │ (Marketplace)│  │ (Inventory)  │  │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  │
│         │                  │                  │          │
│         └──────────────────┼──────────────────┘          │
│                            │                             │
│         ┌──────────────────▼──────────────────┐          │
│         │      Shared Infrastructure           │          │
│         │  • Components (UI, Features)        │          │
│         │  • Utilities (API clients, hooks)   │          │
│         │  • Types & Interfaces               │          │
│         │  • Design System (Tailwind)         │          │
│         └──────────────────┬──────────────────┘          │
│                            │                             │
│         ┌──────────────────▼──────────────────┐          │
│         │      Backend APIs                    │          │
│         │  • REST (Discart-me)                 │          │
│         │  • GraphQL (QRACK, BoxHub)           │          │
│         └──────────────────────────────────────┘          │
└─────────────────────────────────────────────────────────┘

---

Application Boundaries

Personal Website

Router: Pages Router (/pages)
State Management: Local component state, React Context
Data Fetching: Static generation, API routes
Purpose: Public-facing portfolio and blog

Key Characteristics:

• Static-first (most pages pre-rendered)
• No authentication required
• Blog posts via MDX
• Minimal client-side JavaScript

Discart-me

Router: App Router (/app/discart-me)
State Management: Context API (DiscartAuthContext)
Data Fetching: REST API with fetch
Purpose: Community marketplace

Key Characteristics:

• Server-side and client-side rendering
• Authentication via REST endpoints
• Real-time data (items, listings)
• Address-gated content (residents only)

QRACK

Router: App Router (/app/qrack)
State Management: Generic Auth Provider (QrackAuthProvider)
Data Fetching: GraphQL API
Purpose: Container and inventory management

Key Characteristics:

• Mobile-first design
• QR code generation and scanning
• GraphQL for flexible queries
• Uses shared authentication infrastructure

---

Shared Infrastructure

Components

Location: /src/components and /components

Organization:

• /components/ui — Generic, reusable UI primitives (Button, Input, Modal, Loading)
• /src/components/discart-me — Discart-me specific components
• /src/components/qrack — QRACK specific components
• Root /components — Shared layout components (Navbar, Footer, etc.)

Guidelines:

• UI components are domain-agnostic
• Feature components are domain-specific
• All components use TypeScript
• Components in /components/ui follow strict guidelines (see UI Base Guidelines)

Features

Location: /src/features

Feature modules encapsulate related functionality:

• auth/ — Generic authentication system
  • AuthProvider.tsx — Generic auth context
  • useAuth.ts — Generic auth hook
  • Domain-specific providers (e.g., QrackAuthProvider)
• discart-me/ — Discart-me specific features
  • hooks/useImageProcessor.ts — Image processing for uploads
• qrack/ — QRACK specific features
  • hooks/useCreateContainer.ts — Container creation logic
  • components/ — QRACK feature components

Pattern:

features/
  {domain}/
    components/     # Feature-specific UI
    hooks/          # Feature-specific logic
    types.ts        # Feature-specific types

Libraries & Utilities

Location: /src/lib

Core Libraries:

• api/core/graphqlClient.ts — Shared GraphQL client
• qrackApi.ts — QRACK GraphQL API client
• discartMeApi.ts — Discart-me REST API client
• boxhubApi.ts — BoxHub GraphQL API client
• image/ — Shared image processing library
  • processImage.ts — Resize, compress, format conversion
  • utils.ts — Validation, formatting
  • constants.ts — Image presets (marketplace, container, avatar)

Utilities:

• upload.ts — File upload helpers
• utils.ts — General utilities (class merging, etc.)
• toast.ts — Toast notification system

---

Data Flow

Authentication Flow

User Login
    │
    ├─► Domain-specific auth provider (e.g., QrackAuthProvider)
    │   │
    │   ├─► Calls generic AuthProvider with domain config
    │   │
    │   ├─► API call (REST or GraphQL)
    │   │
    │   ├─► Token stored in localStorage
    │   │
    │   └─► User data stored in context
    │
    └─► Protected routes check auth status

Data Fetching Flow

Discart-me (REST):

Component
    │
    ├─► Calls function in discartMeApi.ts
    │   │
    │   ├─► fetch() with Authorization header
    │   │
    │   ├─► Parse JSON response
    │   │
    │   └─► Return typed data

QRACK (GraphQL):

Component
    │
    ├─► Calls function in qrackApi.ts
    │   │
    │   ├─► Uses shared graphqlClient.ts
    │   │   │
    │   │   ├─► Constructs GraphQL query
    │   │   ├─► Adds Authorization header
    │   │   ├─► Handles errors
    │   │   └─► Returns typed response

---

Routing Strategy

App Router (Next.js 13+)

Used by: Discart-me, QRACK

Structure:

app/
  {domain}/
    layout.tsx        # Domain-specific layout
    page.tsx          # Home page
    {route}/
      page.tsx        # Route page
      layout.tsx      # Nested layout (optional)

Benefits:

• Server Components by default
• Nested layouts
• Streaming and Suspense
• Route groups

Pages Router (Legacy)

Used by: Personal website

Structure:

pages/
  index.tsx           # Home page
  {route}.tsx         # Route page
  api/
    {endpoint}.tsx    # API route

Migration Plan: Gradually migrate to App Router (future work)

---

State Management

Local Component State

Most components use useState for local, component-scoped state.

Context API

Used for:

• Authentication state (user, token, loading)
• Application-wide configuration
• Feature flags (future)

Pattern:

// Create context
const MyContext = createContext<MyContextValue | null>(null);

// Provider component
export function MyProvider({ children }: { children: ReactNode }) {
  const [state, setState] = useState<State>(initialState);
  const value = useMemo(() => ({ state, setState }), [state]);
  return <MyContext.Provider value={value}>{children}</MyContext.Provider>;
}

// Custom hook
export function useMyContext() {
  const context = useContext(MyContext);
  if (!context) throw new Error('Must be used within MyProvider');
  return context;
}

React Query (Future)

Some features use @tanstack/react-query for server state management (e.g., comments, ratings). This will be expanded for consistent data fetching patterns.

---

Error Handling

API Errors

GraphQL:

• Errors returned in errors array
• Handled by graphqlClient.ts
• Logged and surfaced to UI

REST:

• HTTP status codes
• Error messages in response body
• Handled by API client functions

UI Error Handling

• Error boundaries for React errors
• Toast notifications for user-facing errors
• Fallback UI components for loading/error states

---

Performance Considerations

Code Splitting

• Next.js automatically splits code by route
• Dynamic imports for heavy dependencies (e.g., QR code libraries)
• Lazy loading for below-the-fold content

Image Optimization

• Next.js Image component for automatic optimization
• Client-side image processing before upload (Discart-me, QRACK)
• Shared image processing library reduces bundle size

Caching

• Static pages cached at build time
• API responses cached via Next.js fetch cache
• localStorage for user authentication state

---

Security

Authentication

• JWT tokens stored in localStorage
• Tokens sent via Authorization: Bearer header
• Token validation on app load
• Protected routes redirect to login

API Security

• CORS handled by backend
• No sensitive data in client-side code
• Environment variables for API URLs

---

Testing Strategy

Current State: Manual testing, no automated tests yet

Future Plans:

• Unit tests for utilities and hooks
• Component tests with React Testing Library
• Integration tests for critical flows
• E2E tests for key user journeys

---

Future Architecture Considerations

Planned Improvements

1. Consolidate Authentication — Migrate all apps to shared auth system
2. Expand React Query — Consistent server state management
3. Micro-frontends — Evaluate for larger scale (if needed)
4. Design Tokens — Formalize design system tokens
5. Storybook — Component library documentation and testing

Scalability

The current architecture supports:

• Adding new applications easily
• Sharing code across products
• Independent deployment (via route-based splitting)
• Gradual migration from Pages to App Router

---

Related Documentation

• Monorepo Structure — Detailed folder organization
• Tech Stack — Technologies and rationale
• Conventions — Coding standards
• Decisions — Architectural decision records