# ehtisham-sadiq/auto-post-manager architecture

> Architecture diagram of the GitHub repository ehtisham-sadiq/auto-post-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ehtisham-sadiq/auto-post-manager
- Repository: https://github.com/ehtisham-sadiq/auto-post-manager

## Overview

##### Project type and purpose
- This is a full-stack “frontend” application built with Next.js (App Router), React, and Tailwind CSS. Its sole responsibility is to provide a modern LinkedIn content management and scheduling UI. It handles authentication via NextAuth.js, session management, routing, UI state, and delegates all business logic and data persistence to a separate backend API.

##### File structure
- Top-level “app/” directory: contains Next.js App Router pages and layouts (public pages, protected area under “(protected)”).
- “pages/api/”: serverless API routes powering NextAuth.js authentication endpoints.
- “components/”: purely client-side or shared UI components (dialogs, cards, navigation).
- “services/”: client-side API clients (analytics-service.ts, post-service.ts, etc.) that call the external backend at NEXT_PUBLIC_API_URL.
- “lib/”: shared utilities (api-client.ts for fetch wrappers, auth.ts for NextAuth config, db.ts probably for in-memory or preview).
- “hooks/”: custom React hooks for UI state (use-toast, use-mobile).
- “public/” and “styles/”: static assets and global styles.
- Config files: next.config.mjs, tailwind.config.ts, tsconfig.json, .env for environment variables.

##### README for additional insights
- Project description confirms: frontend for LinkedIn-CMS, uses NextAuth.js for authentication, protected routes, bulk uploads, templates, analytics, scheduling.
- Mentions external API base URL via NEXT_PUBLIC_API_URL. No database logic lives here.

a. Main components:
- Browser (User’s Client)
- Next.js App Server (SSR/ISR and Router)
– Pages & Layouts (public vs protected)
– NextAuth.js Middleware / API Routes ([...nextauth].ts)
- Client-side “Services” Layer (services/*.ts)
- External Backend API (REST or GraphQL)
- Authentication Provider (NextAuth Credentials flow)
- Static Assets/CDN (public/, fonts, images)
- External 3rd-party services (e.g., image AI generator if any)
b. Relationships & interactions:
1. Browser requests a page → Next.js Server renders (SSR/Server Components) → sends HTML/CSS/JS.
2. Client-side React hydrates → UI components call services/*.ts → fetch to backend API (NEXT_PUBLIC_API_URL).
3. Protected route guard (ProtectedRoute or getServerSession) checks NextAuth session via cookies.
4. Authentication flows: Sign-in/sign-up pages call NextAuth API Route → NextAuth uses Credentials Provider to validate → sets session cookie.
5. Bulk upload: CSV file → csv-uploader component → calls bulk-service.ts → backend → processes.
6. Analytics: stats-card calls analytics-service.ts → external API → returns metrics.
c. Architectural patterns & design principles:
- App Router with nested layouts for separation of public vs protected UI.
- Hooks & service layer for separation of concerns (UI vs data fetching).
- “Fat” client: most logic lives in React components and service modules. Minimal serverless logic only for auth.
- Tailwind + component library for consistent, responsive UI.
d. Relevant technologies/frameworks/libraries:
- Next.js (App Router with server & client components)
- React (hooks, context via auth-provider and theme-provider)
- NextAuth.js (authentication)
- Tailwind CSS (styling)
- TypeScript (type safety)
- Node.js runtime for serverless API routes

##### Essential architectural elements
- Don’t group everything under “frontend”—break out:
- App Router (public vs protected)
- API routes for NextAuth
- Service layer (analytics, posts, templates, schedule)
- Shared UI components vs page-specific components
- Static assets

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Client
    subgraph "User Client" 
        direction TB
        Browser["Web Browser"]:::frontend
        subgraph "UI Layer"
            direction TB
            AuthProvider["Auth Provider"]:::frontend
            ProtectedGuard["Protected Route Guard"]:::frontend
            UIComponents["Core UI Components"]:::frontend
            Hooks["Custom React Hooks"]:::frontend
        end
        Browser -->|"Interacts with"| UIComponents
        Browser -->|"Interacts with"| AuthProvider
    end

    %% Next.js Server
    subgraph "Next.js Server" 
        direction TB
        subgraph "App Router (Public)" 
            direction TB
            AppLayout["Public Layout"]:::server
            HomePage["app/page.tsx"]:::server
            SignInPage["app/auth/signin/page.tsx"]:::server
            SignUpPage["app/auth/signup/page.tsx"]:::server
            BulkUploadPage["app/bulk-upload/page.tsx"]:::server
            AnalyticsPage["app/analytics/page.tsx"]:::server
            SchedulePage["app/schedule/page.tsx"]:::server
            SettingsPage["app/settings/page.tsx"]:::server
            TemplatesPage["app/templates/page.tsx"]:::server
        end
        subgraph "App Router (Protected)" 
            direction TB
            ProtectedLayout["Protected Layout"]:::server
            PostsPage["app/(protected)/posts/page.tsx"]:::server
            PostsLoading["app/(protected)/posts/loading.tsx"]:::server
        end
        subgraph "API Routes (NextAuth)" 
            direction TB
            NextAuthRoute["[...nextauth].ts"]:::server
        end
        AppLayout --> HomePage
        AppLayout --> SignInPage
        AppLayout --> SignUpPage
        AppLayout --> BulkUploadPage
        AppLayout --> AnalyticsPage
        AppLayout --> SchedulePage
        AppLayout --> SettingsPage
        AppLayout --> TemplatesPage
        ProtectedLayout --> PostsPage
        ProtectedLayout --> PostsLoading

        Browser -->|"Page Request"| AppLayout
        Browser -->|"Page Request"| ProtectedLayout
        Browser -->|"Auth Flow"| NextAuthRoute
    end

    %% Service Layer
    subgraph "Client Service Layer"
        direction TB
        AuthService["services/auth-service.ts"]:::frontend
        PostService["services/post-service.ts"]:::frontend
        BulkService["services/bulk-service.ts"]:::frontend
        AnalyticsService["services/analytics-service.ts"]:::frontend
        TemplateService["services/template-service.ts"]:::frontend
        ScheduleService["services/schedule-service.ts"]:::frontend
        APIClient["lib/api-client.ts"]:::util
    end
    UIComponents -->|"Calls API Clients"| AuthService
    UIComponents --> PostService
    UIComponents --> BulkService
    UIComponents --> AnalyticsService
    UIComponents --> TemplateService
    UIComponents --> ScheduleService
    AuthService --> APIClient
    PostService --> APIClient
    BulkService --> APIClient
    AnalyticsService --> APIClient
    TemplateService --> APIClient
    ScheduleService --> APIClient

    %% Utilities
    subgraph "Shared Utilities"
        direction TB
        AuthConfig["lib/auth.ts"]:::util
        Utils["lib/utils.ts"]:::util
        DBPreview["lib/db.ts"]:::util
    end
    NextAuthRoute --> AuthConfig

    %% Hooks
    subgraph "Hooks"
        direction TB
        UseToast["hooks/use-toast.ts"]:::frontend
        UseMobile["hooks/use-mobile.ts"]:::frontend
    end
    Hooks --> UseToast
    Hooks --> UseMobile

    %% Components
    subgraph "Components"
        direction TB
        AuthProviderComp["components/auth-provider.tsx"]:::frontend
        ProtectedGuardComp["components/protected-route.tsx"]:::frontend
    end
    AuthProviderComp --> AuthProvider
    ProtectedGuardComp --> ProtectedGuard

    %% Static Assets
    subgraph "Static Assets / Styles"
        direction TB
        PublicDir["public/"]:::external
        GlobalsCSS["app/globals.css"]:::external
        StylesCSS["styles/globals.css"]:::external
    end
    Browser -->|"Loads"| PublicDir
    Browser -->|"Loads"| GlobalsCSS
    Browser -->|"Loads"| StylesCSS

    %% External Backend
    subgraph "External Backend API"
        direction TB
        BackendAPI["NEXT_PUBLIC_API_URL"]:::external
        AuthProviderExt["Authentication Provider"]:::external
        Database["Database"]:::db
    end
    APIClient -->|"HTTP/HTTPS"| BackendAPI
    NextAuthRoute -->|"Validate Credentials"| AuthProviderExt
    AuthProviderExt -->|"Session Cookie"| Browser
    BackendAPI --> Database

    %% Click Events
    click AppLayout "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/app/layout.tsx"
    click HomePage "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/app/page.tsx"
    click SignInPage "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/app/auth/signin/page.tsx"
    click SignUpPage "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/app/auth/signup/page.tsx"
    click BulkUploadPage "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/app/bulk-upload/page.tsx"
    click AnalyticsPage "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/app/analytics/page.tsx"
    click SchedulePage "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/app/schedule/page.tsx"
    click SettingsPage "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/app/settings/page.tsx"
    click TemplatesPage "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/app/templates/page.tsx"
    click ProtectedLayout "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/app/(protected)/layout.tsx"
    click PostsPage "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/app/(protected)/posts/page.tsx"
    click PostsLoading "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/app/(protected)/posts/loading.tsx"
    click NextAuthRoute "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/pages/api/auth/[...nextauth].ts"
    click AuthConfig "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/lib/auth.ts"
    click AuthProviderComp "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/components/auth-provider.tsx"
    click ProtectedGuardComp "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/components/protected-route.tsx"
    click AuthService "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/services/auth-service.ts"
    click PostService "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/services/post-service.ts"
    click BulkService "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/services/bulk-service.ts"
    click AnalyticsService "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/services/analytics-service.ts"
    click TemplateService "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/services/template-service.ts"
    click ScheduleService "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/services/schedule-service.ts"
    click APIClient "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/lib/api-client.ts"
    click Utils "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/lib/utils.ts"
    click DBPreview "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/lib/db.ts"
    click UseToast "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/hooks/use-toast.ts"
    click UseMobile "https://github.com/ehtisham-sadiq/auto-post-manager/blob/main/hooks/use-mobile.ts"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#0288D1,color:#000
    classDef server fill:#E8F5E9,stroke:#388E3C,color:#000
    classDef external fill:#FFF3E0,stroke:#F57C00,color:#000
    classDef util fill:#F5F5F5,stroke:#9E9E9E,color:#000
    classDef db fill:#CFD8DC,stroke:#455A64,color:#000
```
