Architecture - Macondo Link Manager

Overview

Macondo Link Manager is built with a domain-driven architecture where the backend serves as the single source of truth and the frontend acts as a declarative consumer. This design ensures consistency, predictability, and scalability. The project is organized as a monorepo containing:

Backend (API): Node.js + Fastify + Prisma
Frontend (Web): Next.js 14 with App Router

/
├── api/        # Backend (Fastify + Prisma)
│   ├── src/
│   ├── prisma/
│   └── Dockerfile
│
├── web/        # Frontend (Next.js 14 + App Router)
│   ├── src/
│   └── next.config.ts
│
└── README.md

Domain Model

The system follows a hierarchical domain structure:

Client
 └── Campaign
      └── Link
           ├── Tags (many-to-many)
           └── Clicks

Entities

Client

Represents an agency client. Clients own campaigns and links.Relationships:

Has many Campaigns (one-to-many)
Has many Links (one-to-many)

Cascade behavior:

Deleting a client deletes all associated campaigns and links

Campaign

Represents a marketing campaign associated with a client.Relationships:

Belongs to one Client (many-to-one)
Has many Links (one-to-many)

Cascade behavior:

Deleting a campaign sets campaignId to NULL on associated links (SetNull)

Link

The core entity representing a shortened link.Properties:

originalUrl: The long URL to redirect to
shortCode: Unique identifier for the shortened link
userId: Creator of the link
clientId: Associated client
campaignId: Associated campaign (optional)

Relationships:

Belongs to one User
Belongs to one Client
Belongs to one Campaign (optional)
Has many Tags (many-to-many via LinkTag)
Has many Clicks (one-to-many)

Links are global to the organization, not owned exclusively by campaigns. A link can exist without a campaign.

Tag

Categorization labels that can be applied to links.Relationships:

Has many Links (many-to-many via LinkTag)

Behavior:

Tags are sent as string[] (array of names)
Non-existent tags are created automatically
Updates replace the entire tag set transactionally
No duplicate tags or orphaned relationships

Click

Records each click event on a shortened link.Properties:

timestamp: When the click occurred
ipAddress: IP address of the visitor
userAgent: Browser/device information
country: Determined via GeoIP
city: Determined via GeoIP
isBot: Whether the click is from a bot
botReason: Explanation if detected as bot

Bot detection occurs at write-time, not read-time. The isBot field is persisted, ensuring metrics remain consistent.

Database Schema

The platform uses PostgreSQL with Prisma ORM. Below is the complete schema:

// User model - Agency employees
model User {
  id        String   @id @default(uuid())
  email     String   @unique
  name      String
  avatarUrl String?
  createdAt DateTime @default(now()) @map("created_at")
  updatedAt DateTime @updatedAt @map("updated_at")

  links Link[]

  @@map("users")
}

// Client model - Agency clients
model Client {
  id        String   @id @default(uuid())
  name      String   @unique
  createdAt DateTime @default(now()) @map("created_at")
  updatedAt DateTime @updatedAt @map("updated_at")

  links     Link[]
  campaigns Campaign[]

  @@map("clients")
}

// Campaign model - Marketing campaigns
model Campaign {
  id        String   @id @default(uuid())
  name      String
  clientId  String
  createdAt DateTime @default(now()) @map("created_at")
  updatedAt DateTime @updatedAt @map("updated_at")

  client Client @relation(fields: [clientId], references: [id], onDelete: Cascade)
  links  Link[]

  @@map("campaigns")
}

// Tag model - Link categorization
model Tag {
  id        String   @id @default(uuid())
  name      String   @unique
  createdAt DateTime @default(now()) @map("created_at")
  updatedAt DateTime @updatedAt @map("updated_at")

  links LinkTag[]

  @@map("tags")
}

// Link model - Shortened links
model Link {
  id          String   @id @default(uuid())
  originalUrl String   @map("original_url") @db.Text
  shortCode   String   @unique @map("short_code")
  userId      String   @map("user_id")
  clientId    String   @map("client_id")
  campaignId  String?  @map("campaign_id")
  createdAt   DateTime @default(now()) @map("created_at")
  updatedAt   DateTime @updatedAt @map("updated_at")

  user     User      @relation(fields: [userId], references: [id], onDelete: Cascade)
  client   Client    @relation(fields: [clientId], references: [id], onDelete: Cascade)
  campaign Campaign? @relation(fields: [campaignId], references: [id], onDelete: SetNull)

  tags   LinkTag[]
  clicks Click[]

  @@index([userId])
  @@index([clientId])
  @@index([campaignId])
  @@map("links")
}

// LinkTag model - Many-to-many junction table
model LinkTag {
  linkId     String   @map("link_id")
  tagId      String   @map("tag_id")
  assignedAt DateTime @default(now()) @map("assigned_at")

  link Link @relation(fields: [linkId], references: [id], onDelete: Cascade)
  tag  Tag  @relation(fields: [tagId], references: [id], onDelete: Cascade)

  @@id([linkId, tagId])
  @@index([tagId])
  @@map("link_tags")
}

// Click model - Click tracking
model Click {
  id        String   @id @default(uuid())
  linkId    String   @map("link_id")
  timestamp DateTime @default(now())
  ipAddress String?  @map("ip_address")
  userAgent String?  @map("user_agent") @db.Text
  country   String?
  city      String?
  isBot     Boolean  @default(false)
  botReason String?  @map("bot_reason")

  link Link @relation(fields: [linkId], references: [id], onDelete: Cascade)

  @@index([linkId])
  @@index([timestamp])
  @@map("clicks")
}

Key Schema Features

UUIDs for all primary keys
Cascade deletes for maintaining referential integrity
Indexes on foreign keys and timestamp columns for query performance
Text fields for potentially long content (URLs, user agents)
Optional fields marked with ? for flexible data capture

Technology Stack

Backend (API)

Fastify

High-performance web framework with schema validation and plugin architecture

Prisma

Type-safe ORM for PostgreSQL with migrations and query builder

Zod

Runtime schema validation for API inputs and outputs

JWT

Secure authentication with JSON Web Tokens stored in httpOnly cookies

Key Backend Dependencies:

{
  "fastify": "^5.0.0",
  "@prisma/client": "^6.0.0",
  "@fastify/jwt": "^10.0.0",
  "@fastify/oauth2": "^8.1.2",
  "@fastify/swagger": "^9.5.2",
  "zod": "^4.1.12",
  "geoip-lite": "^1.4.10",
  "maxmind": "^5.0.3"
}

Frontend (Web)

Next.js 14

React framework with App Router for server components and routing

TanStack Query

Powerful data fetching, caching, and state management

shadcn/ui

Beautifully designed components built with Radix UI and Tailwind

React Hook Form

Performant forms with Zod validation

Key Frontend Dependencies:

{
  "next": "^14.2.5",
  "react": "^18.3.1",
  "@tanstack/react-query": "^5.90.11",
  "axios": "^1.13.2",
  "react-hook-form": "^7.68.0",
  "zod": "^4.1.13",
  "tailwindcss": "^4",
  "recharts": "^2.15.4"
}

Infrastructure

Vercel: Frontend hosting with edge network and automatic deployments
Railway: Backend API and PostgreSQL database hosting
Docker: Containerization for local development and deployment
Custom Domains: Production URLs at mcd.ppg.br

Architectural Principles

The system follows these core principles:

Backend as Single Source of Truth

All business logic resides in the backend
Frontend never performs domain calculations
API returns complete, ready-to-render data models
State management is simplified on the client

Persistent State Over Heuristics

Metrics use persisted state (e.g., isBot field)
No runtime calculations or heuristics for critical data
Aggregations are computed by the backend
Historical data remains consistent over time

Transactional Operations

Critical operations use database transactions
Tag updates replace the entire set atomically
No partial states or race conditions
Cascade deletes maintain referential integrity

Global Link Ownership

Links are global to the organization
Links can exist without campaigns
Metrics aggregate across the entire organization
Flexible association with clients and campaigns

Symmetric Create and Update

Create and Update operations follow the same contract
Same validation rules apply to both
Predictable API behavior
Easier client implementation

Backend Responsibilities

The backend handles:

Authentication & Authorization
- Google OAuth integration
- Domain-based access control
- JWT token generation and validation
Data Aggregation
- Count campaigns per client
- Count links per client and campaign
- Calculate click metrics (by date, browser, country, city)
- Filter bot traffic
Business Logic
- URL shortening and validation
- Tag management (create, associate, sync)
- QR code generation
- Bot detection at write-time
Data Persistence
- CRUD operations for all entities
- Transaction management
- Database migrations
- Referential integrity

Frontend Responsibilities

The frontend handles:

User Interface
- Responsive design with Tailwind CSS
- Component composition with shadcn/ui
- Dark/light theme support
Data Fetching & Caching
- TanStack Query for server state
- Optimistic updates
- Cache invalidation
- Loading and error states
Form Management
- React Hook Form for performance
- Zod schema validation
- Client-side validation feedback
Routing & Navigation
- Next.js App Router
- Dynamic routes for clients, campaigns, links
- Server components where applicable

The frontend never performs domain calculations like counting, filtering, or aggregating. It only displays data provided by the backend.

Data Flow

Here’s how data flows through the system:

Click Tracking Flow

User visits shortened link (https://li.mcd.ppg.br/{shortCode})
Backend receives redirect request
Backend extracts IP, user agent
Backend performs bot detection
Backend determines country/city via GeoIP
Backend creates click record with isBot flag
Backend redirects to original URL
Metrics queries only count clicks where isBot = false

Dashboard Metrics Flow

Frontend requests dashboard data
Backend queries database with joins and aggregations
Backend filters out bot clicks
Backend groups by date, browser, country, city
Backend returns structured metrics
Frontend renders charts using Recharts
TanStack Query caches result

Authentication Flow

JWTs are stored in httpOnly cookies to prevent XSS attacks. The frontend never accesses the token directly.

Read Models

The backend provides optimized read models for list views: Client List:

{
  id: string
  name: string
  campaignCount: number  // Aggregated by backend
  linkCount: number      // Aggregated by backend
  createdAt: string
}

Campaign List:

{
  id: string
  name: string
  clientId: string
  clientName: string     // Joined by backend
  linkCount: number      // Aggregated by backend
  createdAt: string
}

Link List:

{
  id: string
  originalUrl: string
  shortCode: string
  clientId: string
  campaignId: string | null
  tags: { id: string; name: string }[]  // Joined by backend
  clickCount: number     // Aggregated by backend
  createdAt: string
}

These read models eliminate the need for frontend calculations and ensure consistent data representation across all views.

Scalability Considerations

Database

Indexed foreign keys for fast joins
Indexed timestamps for time-based queries
Partitioning strategy for clicks table (future)
Connection pooling via Prisma

API

Fastify’s high-performance event loop
Stateless design for horizontal scaling
Swagger documentation for API discovery
Health check endpoint for monitoring

Frontend

Static generation where possible
Server components to reduce client JS
Code splitting via Next.js
TanStack Query caching to reduce API calls

Monitoring & Health

The API provides a health check endpoint:

GET /health

Response:

{
  "status": "ok",
  "dbConnection": "healthy"
}

Use this endpoint for:

Container health checks
Load balancer probes
Uptime monitoring
CI/CD pipeline validation

Next Steps

API Reference

Explore all available endpoints

Core Features

Learn about link management and features

Database Guide

Manage schema changes with Prisma

Deployment

Deploy to production environments

Get Started

Core Features

Guides

​Overview

​Domain Model

​Entities

​Database Schema

​Key Schema Features

​Technology Stack

​Backend (API)

Fastify

Prisma

Zod

JWT

​Frontend (Web)

Next.js 14

TanStack Query

shadcn/ui

React Hook Form

​Infrastructure

​Architectural Principles

​Backend Responsibilities

​Frontend Responsibilities

​Data Flow

​Link Creation Flow

​Click Tracking Flow

​Dashboard Metrics Flow

​Authentication Flow

​Read Models

​Scalability Considerations

​Database

​API

​Frontend

​Monitoring & Health

​Next Steps

API Reference

Core Features

Database Guide

Deployment

Build docs developers (and LLMs) love

Overview

Domain Model

Entities

Database Schema

Key Schema Features

Technology Stack

Backend (API)

Frontend (Web)

Infrastructure

Architectural Principles

Backend Responsibilities

Frontend Responsibilities

Data Flow

Link Creation Flow

Click Tracking Flow

Dashboard Metrics Flow

Authentication Flow

Read Models

Scalability Considerations

Database

API

Frontend

Monitoring & Health

Next Steps