Front-end Architecture

A quick guide for frontend engineers to understand Plantfolio's modern architecture.

Monorepo Structure

Plantfolio is a Turborepo monorepo with three Next.js applications and shared packages:

  • apps/dashboard — Main user dashboard (Next.js 16 App Router)
  • apps/web — Marketing website (Next.js 16 App Router)
  • apps/admin — Internal admin tools
  • packages/* — Shared libraries and utilities

Core Technology Stack

Frontend Framework

  • Next.js 16 with App Router (React Server Components), Turbopack for builds
  • React 19 — Latest React with concurrent features
  • TypeScript — Strict type safety across the entire codebase

UI & Styling

AI & Data

  • Vercel AI SDK — AI features (e.g. plant identification flows)
  • OpenAI GPT-4 / Google Gemini — Plant identification and advice
  • PostgreSQL with Prisma 7 — Primary database (main + plants)
  • Clerk — Authentication (via @plantfolio/auth)

Development Tools

Key Shared Packages

  • @plantfolio/design-system — Unified UI components and design tokens
  • @plantfolio/db — Prisma schema and database utilities
  • @plantfolio/utils — Shared utilities including error handling
  • @plantfolio/plants — Plant data entities and business logic
  • @plantfolio/search — Plant search and indexing functionality

Architecture Patterns

Server Components First

Default to React Server Components for better performance. Minimize use client directives — only when interactivity is needed. Data fetching happens at the server level when possible.

Route Organization

App Router with nested layouts for efficient loading. Route groups: (garden), (profile), (folio-plants), (settings), (public-profile), (public-folio) for logical organization. Dynamic routes [username], [folioSlug] for user-specific content.

State Management

  • React Hook Form for complex form state
  • Zustand for global client state (when necessary)
  • Server state via React Server Components and Suspense

Dashboard App Architecture

The main user-facing application is organized into logical route groups:

  • (garden) — Core gardening features, plant management, folios
  • (profile) — Authentication, account settings, billing
  • (folio-plants) — Plant detail pages, journal, signs
  • (settings) — Folio settings, signs, awards, brand
  • (public-profile), (public-folio) — Public share views
  • api — API routes for data fetching and server actions

Note: apps/admin is a separate app for internal admin tools.

Key Architectural Decisions

1. TypeScript-First

Strict TypeScript configuration across the entire monorepo. Shared type definitions via packages for consistency.

2. Error Handling

Centralized error capture utility; errors flow through a single interface rather than direct provider calls.

3. Database Strategy

PostgreSQL with Prisma ORM for type-safe database operations. Prisma validation where possible, enhanced with Zod when needed.

4. Navigation

Use Next.js navigation methods and centralized URL utilities. Avoid direct window.location manipulation.

Getting Started Links

← Back to overview