# nazmul-nhb/next-portfolio architecture

> Architecture diagram of the GitHub repository nazmul-nhb/next-portfolio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nazmul-nhb/next-portfolio
- Repository: https://github.com/nazmul-nhb/next-portfolio

## Overview

1. **Overall shape**
   - This is a **Next.js App Router** application with a strong split between:
     - **public-facing content** pages,
     - a **rich admin dashboard**,
     - a large set of **self-contained productivity tools**,
     - and a shared **REST-style API layer** under `src/app/api`.
   - Most business logic is concentrated in `src/lib`, while pages and route handlers stay thin and delegate to those shared modules.

2. **Primary runtime boundaries**
   - The app runs as a **server-rendered Next.js site** with mixed server/client components.
   - Interactive areas such as the admin console, editors, chat, and tools are mostly client components.
   - Cross-cutting providers in `src/providers` handle **auth**, **TanStack Query**, and **theme** state across the UI.

3. **Public site subsystem**
   - The landing page lives in `src/app/(home)` and is composed from section components like hero, skills, projects, testimonials, blogs, and career highlights.
   - Content pages for **about**, **projects**, **blogs**, **resume**, **contact**, **messages**, **settings**, and **users** all follow the same pattern: a route-level page plus focused feature components.
   - These pages typically read from the API or DB-backed server data, then render with shared UI primitives from `src/components`.

4. **Content management subsystem**
   - The repo models several content domains: **blogs, projects, skills, experiences, education, testimonials, categories, tags, users, and messages**.
   - Each domain has:
     - a schema in `src/lib/drizzle/schema`,
     - validation in `src/lib/zod-schema`,
     - API routes under `src/app/api/...`,
     - and admin UI under `src/app/admin/...`.
   - This creates a clear flow: **form/UI → validated request → API route → Drizzle/Postgres**.

5. **Admin dashboard**
   - `src/app/admin` is the operational center for CRUD and sorting workflows.
   - It contains dedicated sections for blogs, categories, education, experience, projects, skills, testimonials, messages, and users.
   - Client components such as `AdminBlogsClient`, `ProjectsClient`, and `SortableSkillCard` imply heavy client-side interaction for tables, dialogs, drag-and-drop ordering, and editing flows.

6. **Database layer**
   - Persistence is built on **Drizzle ORM** with a PostgreSQL database, likely Neon as described in the README.
   - `drizzle.config.ts`, `migrations/`, and `src/lib/drizzle/schema/*` define the schema/migration boundary.
   - The database appears to be the system of record for:
     - user accounts,
     - blog content and metadata,
     - project/career records,
     - messaging/conversations,
     - polls,
     - and expense-manager data.
   - The migration history suggests the schema evolved incrementally and is managed explicitly rather than being generated at runtime.

7. **Authentication and user identity**
   - Authentication is handled through **NextAuth v5** in `src/lib/auth.ts` and `src/app/api/auth/[...nextauth]`.
   - The app supports **credentials and Google OAuth**.
   - User-aware APIs like `users/me`, `users/search`, `users/admin`, and messaging endpoints indicate a central identity model shared across public and admin features.
   - There is also a login/register/error/force-signout flow under `src/app/auth`.

8. **Messaging subsystem**
   - Messaging is implemented as a database-backed conversation system rather than WebSockets.
   - The UI under `src/app/messages` uses conversation lists and chat area components, while API routes under `src/app/api/messages/*` expose conversations, unread counts, and message-by-conversation access.
   - The README notes the “almost real-time” behavior: the client likely **polls** for updates via TanStack Query or custom hooks.
   - This makes messaging a distinct subsystem with a polling-driven data flow: **client poll → API → DB → refreshed conversation state**.

9. **Media, uploads, and external services**
   - **Cloudinary** is the media backend for uploads and image management, with route support in `src/app/api/uploads`.
   - **Nodemailer** is used for email notifications, most visibly around contact and perhaps auth-related workflows.
   - The resume feature also references an externally hosted PDF URL, so the app combines **local generated views** with **remote document delivery**.
   - These integrations are abstracted under `src/lib/actions/cloudinary.ts`, `src/lib/email`, and related helpers.

10. **Blog/editor and publishing workflow**
   - Blog creation/editing is handled through a richer editor stack, with Tiptap-based editor support mentioned in the README and components under `src/components/misc/blog-editor.tsx`.
   - Blog routes include list/detail pages, personal posts, create/edit flows, admin management, reactions, and comments.
   - This subsystem is a good example of the app’s layering:
     - content editing in the client,
     - validation in Zod,
     - persistence through API routes and Drizzle,
     - and presentation via public blog pages plus social/SEO helpers.

11. **Tools subsystem**
   - `src/app/tools` is effectively a mini product suite inside the portfolio.
   - Tools are mostly independent pages with local UI and a small shared shell (`Navigate`, `PoweredBy`, `TitleWithShare`).
   - Some tools are pure client-side utilities, while others call dedicated APIs under `src/app/api/tools/*`.
   - Notable data-heavy tools include:
     - **expense manager**,
     - **crowd polls**,
     - **npm package lookup**,
     - and utilities that may rely on browser storage or local computation.

12. **Tool-specific persistence and state**
   - Some tools use more than transient UI state:
     - **crowd polls** has dedicated poll, vote, and analytics endpoints,
     - **expense manager** has entries, loans, payments, summary, and currency routes,
     - and some utilities reference `src/lib/tools/indexed-db.ts`, indicating browser-side persistence for selected features.
   - `src/lib/store` contains Zustand stores for reusable interactive state, likely used by messaging and UI bubbles.
   - This means the tools area is not just static calculators; it mixes **local computation**, **client persistence**, and **DB-backed feature tools**.

13. **Shared component and design system**
   - `src/components/ui` is the base design system, combining shadcn-style primitives and Radix UI components.
   - Higher-level shared components in `src/components/forms`, `src/components/nav`, and `src/components/misc` support reuse across the app.
   - These shared components are the main architectural boundary for consistency: feature pages are assembled from them rather than implementing bespoke UI each time.

14. **API and service conventions**
   - API routes are organized by domain and generally mirror the UI sections one-for-one.
   - `src/lib/actions` provides request/response helpers and shared server-side utilities, which keeps route handlers standardized.
   - Zod schemas in `src/lib/zod-schema` and typed interfaces in `src/types` enforce a contract between UI, API, and DB.
   - The result is a fairly strict vertical slice architecture: **feature page → component → API route → service/helper → DB/external service**.

15. **SEO and platform concerns**
   - The app has dedicated support for **OpenGraph images**, `robots.ts`, and `sitemap.ts`.
   - This suggests the public content areas are treated as indexed, shareable products rather than internal tooling.
   - Next.js image/metadata routes are used as part of the rendering layer, not as separate services.

16. **What to draw in an architecture diagram**
   - The most important boxes are:
     - **Next.js App Router UI** with public pages, admin, auth, messages, tools,
     - **API routes** grouped by domain,
     - **Shared libs** for auth, Drizzle, email, uploads, validation, and utility tools,
     - **PostgreSQL/Neon** as the main datastore,
     - **Cloudinary**, **Google OAuth/NextAuth**, and **email** as external dependencies.
   - The key flows are:
     - content CRUD from admin/public forms to DB,
     - blog/contact/message interactions through APIs,
     - tool-specific fetches and polling,
     - and media/auth integration through external providers.

Main entry points: [`src/lib`](https://github.com/nazmul-nhb/next-portfolio/tree/main/src/lib) (Shared Lib), [`src/app`](https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app) (App Router), [`src/app/api`](https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app/api) (API Routes), [`src/components`](https://github.com/nazmul-nhb/next-portfolio/tree/main/src/components) (Shared Components)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Next.js UI"]
  node_app["App Router<br/>nextjs app"]
  node_home["Home<br/>public pages"]
  node_public_content["Content Pages<br/>public routes"]
  node_admin["Admin Console<br/>dashboard"]
  node_auth_ui["Auth UI<br/>auth routes"]
  node_messages_ui["Messaging UI<br/>chat UI"]
  node_tools_ui["Tools Hub<br/>tool suite"]
end

subgraph group_api["API Layer"]
  node_api_root["API Routes<br/>rest handlers"]
  node_content_api["Content APIs<br/>domain api"]
  node_messaging_api["Messaging APIs<br/>domain api"]
  node_tool_api["Tool APIs<br/>feature api"]
  node_auth_api["Auth APIs"]
end

subgraph group_lib["Shared Logic"]
  node_shared_lib["Shared Lib<br/>service layer"]
  node_db_schema[("Drizzle Schema<br/>data model")]
  node_validation["Zod Schemas<br/>validation"]
end

subgraph group_components["Shared Components"]
  node_shared_components["Shared Components<br/>ui kit"]
end

subgraph group_platform["Platform"]
  node_providers["Providers"]
  node_postgres[("PostgreSQL<br/>database")]
  node_external_services["External Services<br/>integrations"]
end

node_app -->|"renders"| node_home
node_app -->|"routes"| node_public_content
node_app -->|"hosts"| node_admin
node_app -->|"hosts"| node_auth_ui
node_app -->|"hosts"| node_messages_ui
node_app -->|"hosts"| node_tools_ui
node_home -.->|"uses"| node_shared_components
node_public_content -.->|"uses"| node_shared_components
node_admin -.->|"uses"| node_shared_components
node_messages_ui -.->|"uses"| node_providers
node_tools_ui -.->|"uses"| node_providers
node_api_root -->|"organizes"| node_content_api
node_api_root -->|"organizes"| node_messaging_api
node_api_root -->|"organizes"| node_tool_api
node_api_root -->|"organizes"| node_auth_api
node_content_api -.->|"delegates"| node_shared_lib
node_messaging_api -.->|"delegates"| node_shared_lib
node_tool_api -.->|"delegates"| node_shared_lib
node_auth_api -.->|"delegates"| node_shared_lib
node_shared_lib -.->|"validates"| node_validation
node_shared_lib -->|"persists"| node_db_schema
node_db_schema -->|"stores"| node_postgres
node_shared_lib -.->|"integrates"| node_external_services
node_providers -.->|"supplies"| node_shared_components

click node_app "https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app"
click node_home "https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app/(home)"
click node_public_content "https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app"
click node_admin "https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app/admin"
click node_auth_ui "https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app/auth"
click node_messages_ui "https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app/messages"
click node_tools_ui "https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app/tools"
click node_api_root "https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app/api"
click node_content_api "https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app/api"
click node_messaging_api "https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app/api/messages"
click node_tool_api "https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app/api/tools"
click node_auth_api "https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app/api/auth"
click node_shared_lib "https://github.com/nazmul-nhb/next-portfolio/tree/main/src/lib"
click node_db_schema "https://github.com/nazmul-nhb/next-portfolio/tree/main/src/lib/drizzle/schema"
click node_validation "https://github.com/nazmul-nhb/next-portfolio/tree/main/src/lib/zod-schema"
click node_providers "https://github.com/nazmul-nhb/next-portfolio/tree/main/src/providers"
click node_shared_components "https://github.com/nazmul-nhb/next-portfolio/tree/main/src/components"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_home,node_public_content,node_admin,node_auth_ui,node_messages_ui,node_tools_ui toneBlue
class node_api_root,node_content_api,node_messaging_api,node_tool_api,node_auth_api toneAmber
class node_shared_lib,node_db_schema,node_validation toneMint
class node_shared_components toneRose
class node_providers,node_postgres,node_external_services toneIndigo
```

## Components

### Next.js UI

App Router pages and route-level feature UIs

- [App Router](https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app): nextjs app · Server-rendered application shell with mixed server/client routes · `src/app`
- [Home](https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app/(home)): public pages · Landing page and public content sections · `src/app/(home)`
- [Content Pages](https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app): public routes · About, projects, blogs, resume, contact, settings, and users pages · `src/app`
- [Admin Console](https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app/admin): dashboard · CRUD and sorting workspace for content domains · `src/app/admin`
- [Auth UI](https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app/auth): auth routes · Login, register, error, and forced sign-out flows · `src/app/auth`
- [Messaging UI](https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app/messages): chat UI · Conversation list and chat views for user messaging · `src/app/messages`
- [Tools Hub](https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app/tools): tool suite · Standalone productivity tools and their local shells · `src/app/tools`

### API Layer

Route handlers grouped by domain

- [API Routes](https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app/api): rest handlers · Thin route handlers that expose domain APIs · `src/app/api`
- [Content APIs](https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app/api): domain api · Blogs, projects, categories, tags, comments, resume, contact, and users endpoints · `src/app/api`
- [Messaging APIs](https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app/api/messages): domain api · Conversation, unread, and message retrieval/update endpoints · `src/app/api/messages`
- [Tool APIs](https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app/api/tools): feature api · Expense manager, polls, npm lookup, and upload endpoints · `src/app/api/tools`
- [Auth APIs](https://github.com/nazmul-nhb/next-portfolio/tree/main/src/app/api/auth): auth api · NextAuth, registration, and OTP routes · `src/app/api/auth`

### Shared Logic

Reusable server and client logic

- [Shared Lib](https://github.com/nazmul-nhb/next-portfolio/tree/main/src/lib): service layer · Server helpers, validation, auth, email, uploads, and utility modules · `src/lib`
- [Drizzle Schema](https://github.com/nazmul-nhb/next-portfolio/tree/main/src/lib/drizzle/schema): data model · Database tables and migrations for blogs, careers, users, messages, polls, skills, testimonials, and expenses · `src/lib/drizzle/schema`
- [Zod Schemas](https://github.com/nazmul-nhb/next-portfolio/tree/main/src/lib/zod-schema): validation · Request and domain validation contracts shared across UI and APIs · `src/lib/zod-schema`

### Shared Components

Cross-feature UI building blocks

- [Shared Components](https://github.com/nazmul-nhb/next-portfolio/tree/main/src/components): ui kit · Reusable forms, nav, misc helpers, and base UI primitives · `src/components`

### Platform

Providers and external systems

- [Providers](https://github.com/nazmul-nhb/next-portfolio/tree/main/src/providers): state providers · Auth, query, and theme context for the app · `src/providers`
- **PostgreSQL**: database · Primary persistent store, likely Neon-backed
- **External Services**: integrations · Cloudinary, Google OAuth, email delivery, and NextAuth providers

## Connections

- App Router → Home: renders · App Router composes public landing content
- App Router → Content Pages: routes · Public pages share the same application shell
- App Router → Admin Console: hosts · Admin dashboard is a major UI boundary
- App Router → Auth UI: hosts · Authentication pages live in the app router
- App Router → Messaging UI: hosts · Messaging is a first-class interactive section
- App Router → Tools Hub: hosts · Tool pages are implemented as a mini product suite
- Home → Shared Components: uses · Landing sections are assembled from reusable UI
- Content Pages → Shared Components: uses · Content pages rely on shared forms, nav, and primitives
- Admin Console → Shared Components: uses · Dashboard CRUD screens use shared tables, dialogs, and forms
- Messaging UI → Providers: uses · Chat state depends on auth and query context
- Tools Hub → Providers: uses · Tools reuse query/theme/auth context where needed
- API Routes → Content APIs: organizes · Domain route handlers are grouped under the API layer
- API Routes → Messaging APIs: organizes · Messaging endpoints are a dedicated API slice
- API Routes → Tool APIs: organizes · Tool-specific services are exposed through routes
- API Routes → Auth APIs: organizes · Authentication flows are served through API routes
- Content APIs → Shared Lib: delegates · Handlers validate, normalize, and persist through shared services
- Messaging APIs → Shared Lib: delegates · Conversation logic is implemented in shared server modules
- Tool APIs → Shared Lib: delegates · Tool endpoints reuse common helpers and specialized utilities
- Auth APIs → Shared Lib: delegates · Auth routes rely on the shared auth and email layer
- Shared Lib → Zod Schemas: validates · Zod schemas define the input contract for features
- Shared Lib → Drizzle Schema: persists · Drizzle models define application storage
- Drizzle Schema → PostgreSQL: stores · Migrations and schema target the relational database
- Shared Lib → External Services: integrates · Uploads, OAuth, and email are abstracted behind helpers
- Providers → Shared Components: supplies · Global UI state and context feed reusable components