by @must_be_ash

Architecture – Utilities

Understanding lib, utils, hooks, middleware, and configuration files

What Are Utilities?

These are folders where little bits of logic live. You don't usually open or edit these directly unless AI tells you to — but knowing what they are helps you understand how your app works behind the scenes.

lib/ - Connection Hub

This is where important connections live. Think of this as the folder where your app keeps all its "wires" to other services.

What lives in lib/:

🗄️ Database Connections

Files like:

  • mongodb.ts - Connect to MongoDB database
  • prisma.ts - Prisma database client setup
  • supabase.ts - Supabase connection

🔗 External Services

Connection files for:

  • openai.ts - OpenAI API client
  • stripe.ts - Stripe payment setup
  • auth.ts - Authentication configuration
  • farcaster.ts - Farcaster integration

📧 Communication Services

Setup for:

  • email.ts - Email service configuration
  • notifications.ts - Push notification setup
  • sms.ts - SMS service connections

Whenever your app needs to talk to something outside itself, the code for that connection lives here.

utils.ts - Helper Toolbox

This is your app's toolbox. It holds little helpers that clean things up or make things easier.

Common helper functions:

📅 Date & Time Helpers

  • Convert dates: 2024-06-04 → June 4, 2024
  • Time ago formatting: 2 hours ago
  • Timezone conversions
  • Date range calculations

✅ Validation Helpers

  • Check if email format is valid
  • Ensure usernames aren't too long
  • Validate phone numbers
  • Password strength checking

🔧 Text & ID Helpers

  • Generate random short IDs
  • Clean and format user input
  • Truncate long text with "..."
  • Convert text to URL-friendly formats

💱 Number & Currency Helpers

  • Format prices: 1500 → $15.00
  • Number abbreviations: 1000 → 1K
  • Percentage calculations
  • Currency conversions

You don't need to do anything here unless AI asks — but this file helps AI reuse code instead of writing the same thing again and again.

hooks/ - Smart Shortcuts

This is a folder for smart shortcuts. These are special tools that help pages and components keep track of something or remember things.

Common hooks (in plain English):

👤 useUser.ts

"Remember who the user is across different pages"

⏳ useDebounce.ts

"Wait a bit before doing something (like searching while someone types)"

📊 useLocalStorage.ts

"Remember user preferences even after they close the browser"

🔄 useApi.ts

"Handle loading states and errors when fetching data"

🎯 useClickOutside.ts

"Know if someone clicked outside a modal or dropdown to close it"

You don't need to know how these work — but if you see AI creating or using a file from hooks/, it's just a smart way of simplifying something that shows up in multiple places.

middleware.ts - Security Guard

Think of this file like a security guard at the door. Before someone sees a page on your site or triggers something (like an API), this file checks who they are and whether they're allowed in.

What middleware does:

🚪 Access Control

  • Block users who aren't signed in
  • Check user permissions for specific pages
  • Verify subscription status for premium features

🔄 Redirects

  • Send users to login page if not authenticated
  • Redirect to onboarding for new users
  • Handle custom domain routing

🔍 Pre-checks

  • Run security checks before page loads
  • Validate request headers
  • Rate limiting and bot protection

You don't need to know how it works — just know that this is where those checks happen. If your app needs some logic to happen before a page loads or an API runs, AI will likely create or edit this file.

next.config.js - App Settings

This file is your app's settings panel. It tells Next.js (the tool running your app) how to behave — kind of like flipping switches or setting preferences.

Common configurations:

🖼️ Image Settings

  • Which domains images can load from
  • Image optimization settings
  • Default image sizes and formats

🔧 Build Configuration

  • Experimental Next.js features
  • Bundle optimization settings
  • Compiler options

🌐 Routing & Redirects

  • Custom redirects and rewrites
  • Internationalization (i18n) setup
  • Custom headers

📁 File Handling

  • Support for special file types
  • Static file serving rules
  • Asset optimization

When AI might edit this:

  • You ask to load images from another website
  • You're adding special features (like MDX support, PWA features)
  • You're deploying your app and need to allow something new
  • You need custom redirects or domain handling

If your app ever says "not allowed" or "failed to load," this file might be where the fix goes.

💡 Think of it as:

The control panel for your app's behavior — it defines the rules for how your app runs and what it's allowed to do.

Working with Utilities

✅ Do This

  • Let AI handle these files for you
  • Ask AI to explain what a utility function does
  • Trust that these files are working behind the scenes
  • Ask AI before modifying configuration files

❌ Avoid This

  • Don't edit these files manually unless you know what you're doing
  • Don't delete utility files that seem "unused"
  • Don't modify middleware without understanding the security implications
  • Don't change next.config.js randomly

🤝 Working with AI

  • Ask AI to create utility functions for repeated tasks
  • Request explanations when you see these files mentioned
  • Let AI set up configurations and connections
  • Ask for comments in utility files to understand their purpose