# nasirsultan/shoulty-ai architecture

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

- Interactive diagram: https://gitdiagram.com/nasirsultan/shoulty-ai
- Repository: https://github.com/nasirsultan/shoulty-ai

## Overview

1. This repository is a Next.js App Router application written in TypeScript. It combines a public marketing site, authenticated product dashboards, admin consoles, and a set of serverless API routes inside one codebase.

2. The top-level architectural boundary is route-based. The `app/` directory is split into many route groups and nested layouts:
   - public pages like landing, pricing, case studies, careers, policy, terms
   - auth flows under `app/(auth)` and other sign-in/sign-up routes
   - product dashboards under `app/dashboards`, `app/calendar-dashboard`, `app/editorial-calendar`
   - internal/admin surfaces under `app/admin`, `app/content-admin`, `app/finance-admin`, `app/technical-admin`

3. The public site is composed primarily from reusable marketing components in `components/` such as `HeroSection`, `PricingSection`, `SocialProof`, `Footer`, `Header`, and industry-oriented sections. This part is mostly presentation and SEO-driven, with supporting Open Graph and sitemap/robots files in `app/`.

4. Authentication and onboarding are a distinct subsystem. Pages under `app/(auth)` and `app/sign-in` / `app/sign-up` cover sign-in, sign-up, password reset, verification, and profile setup. The auth implementation is backed by `app/api/auth/[...nextauth]/route.ts` and custom auth UI in `components/auth/`.

5. The authenticated application center is the `app/dashboards/` area. It has its own layout, header/sidebar components, auth guard, and multiple functional sections like analytics, library, notifications, team, settings, billing, accounts, and brand. This is the main logged-in workspace rather than a single monolithic dashboard.

6. Calendar functionality is a major product subsystem. There is a dedicated `app/calendar-dashboard` page, a richer `app/dashboards/calendar` area, a `components/calendar/Calendar.tsx` UI, and hooks such as `useCalendarApi.ts`. The repo also includes `data/calendar-posts.json`, suggesting a mix of server-generated and local/mock calendar content.

7. Content generation is handled through dedicated API routes and client wrappers. The `api/` directory contains typed client modules like `calendarApi.ts`, `calendarPostsApi.ts`, `postGeneratorApi.ts`, `textGeneratorApi.ts`, `homeApi.tsx`, and `configApi.tsx`, while the server endpoints live under `app/api/generator`, `app/api/post-generator`, `app/api/prompt-images`, and `app/api/gemeini-image`. This separation suggests frontend components call API wrapper modules, which then target Next.js route handlers.

8. There is a streaming/proxy layer for longer-running generation workflows. Routes under `app/api/proxy/stream-posts` and `app/api/proxy/stream-posts-save` imply server-mediated streaming of generated posts, likely to support incremental output and persistence without exposing the downstream service directly to the browser.

9. The repo also includes a profile, media, and display-image subsystem. Components like `Profile.tsx`, `ImageModal.tsx`, `PostPopup.tsx`, and the `app/api/display-images` route indicate generated or fetched assets are displayed and managed separately from text generation.

10. Shared UI and shell behavior are centralized in reusable building blocks:
   - `layout/` and `components/sidebar`, `components/header`, `layout/AppHeader`, `layout/AppSidebar`
   - `context/SidebarContext.tsx` and `context/ThemeContext.tsx` for app-wide UI state
   - `hooks/` for page-level behaviors like back navigation, modal state, sidebar state, user profile, and industry selection
   This keeps navigation and theme state outside individual pages.

11. The codebase uses a design-system style component library under `components/ui`, `components/form`, `components/tables`, `components/charts`, and `components/common`. Those are used by both marketing pages and dashboards, which keeps the visual layer consistent across public and authenticated sections.

12. Static assets and deployment artifacts are important to the architecture. `public/images`, `public/videos`, and `public/templates` support rich marketing and dashboard content, while `next.config.ts`, Tailwind, PostCSS, and `types/next-auth.d.ts` indicate a production-oriented Next.js frontend with typed auth integration.

13. Overall data flow is: browser routes render pages/layouts, pages compose shared UI components, client-side hooks and API wrapper modules call Next.js route handlers, and those routes coordinate auth, calendar, and generation features. The application is therefore a frontend-heavy product with embedded backend-for-frontend endpoints rather than a separate standalone API service.

Main entry points: [`app/dashboards/page.tsx`](https://github.com/nasirsultan/shoulty-ai/blob/main/app/dashboards/page.tsx) (Dashboard shell), [`api/calendarApi.ts`](https://github.com/nasirsultan/shoulty-ai/blob/main/api/calendarApi.ts) (Calendar API), [`components/auth/SignInForm.tsx`](https://github.com/nasirsultan/shoulty-ai/blob/main/components/auth/SignInForm.tsx) (Auth form), [`components/HeroSection.tsx`](https://github.com/nasirsultan/shoulty-ai/blob/main/components/HeroSection.tsx) (Hero section)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public site"]
  node_app_home["Home<br/>route<br/>[page.tsx]"]
  node_app_pricing["Pricing<br/>route<br/>[page.tsx]"]
  node_app_cases["Case studies<br/>route<br/>[page.tsx]"]
  node_app_industry["Industry pages<br/>route<br/>[page.tsx]"]
end

subgraph group_auth["Auth"]
  node_auth_signin["Sign in<br/>auth route<br/>[page.tsx]"]
  node_auth_signup["Sign up<br/>auth route<br/>[page.tsx]"]
  node_auth_flow["Onboarding<br/>auth route group<br/>[page.tsx]"]
end

subgraph group_workspace["App workspace"]
  node_dashboard_shell["Dashboard shell<br/>workspace route<br/>[page.tsx]"]
  node_analytics["Analytics<br/>workspace route<br/>[page.tsx]"]
  node_calendar_workspace["Calendar<br/>workspace route<br/>[page.tsx]"]
  node_calendar_page["Calendar app<br/>product route<br/>[page.tsx]"]
  node_editorial_calendar["Editorial calendar<br/>product route<br/>[page.tsx]"]
end

subgraph group_admin["Admin"]
  node_admin_hub["Admin hub<br/>admin route<br/>[page.tsx]"]
  node_content_admin["Content admin<br/>admin route<br/>[page.tsx]"]
  node_finance_admin["Finance admin<br/>admin route<br/>[page.tsx]"]
  node_tech_admin["Technical admin<br/>admin route<br/>[page.tsx]"]
end

subgraph group_platform["Platform"]
  node_hero_section["Hero section<br/>marketing component<br/>[HeroSection.tsx]"]
  node_footer["Footer<br/>marketing component<br/>[Footer.tsx]"]
  node_signin_form["Auth form<br/>auth component<br/>[SignInForm.tsx]"]
  node_nextauth["Auth API<br/>route handler<br/>[route.ts]"]
  node_app_header["App header<br/>shell component<br/>[AppHeader.tsx]"]
  node_app_sidebar["App sidebar<br/>shell component<br/>[AppSidebar.tsx]"]
  node_calendar_ui["Calendar UI<br/>product component<br/>[Calendar.tsx]"]
  node_calendar_api["Calendar API<br/>client module<br/>[calendarApi.ts]"]
  node_text_gen_api["Text gen API<br/>route handler<br/>[route.ts]"]
  node_post_gen_api["Post gen API<br/>route handler<br/>[route.ts]"]
  node_stream_proxy["Stream proxy<br/>route handler<br/>[route.ts]"]
  node_sidebar_ctx(("Sidebar state<br/>context<br/>[SidebarContext.tsx]"))
  node_theme_ctx(("Theme state<br/>context<br/>[ThemeContext.tsx]"))
end

node_app_home -->|"composes"| node_hero_section
node_app_home -->|"composes"| node_footer
node_app_pricing -->|"uses"| node_hero_section
node_app_cases -->|"uses"| node_hero_section
node_app_industry -->|"uses"| node_hero_section
node_auth_signin -->|"renders"| node_signin_form
node_auth_signup -->|"renders"| node_signin_form
node_auth_flow -->|"renders"| node_signin_form
node_signin_form -->|"authenticates"| node_nextauth
node_dashboard_shell -->|"uses"| node_app_header
node_dashboard_shell -->|"uses"| node_app_sidebar
node_dashboard_shell -->|"depends on"| node_sidebar_ctx
node_dashboard_shell -->|"depends on"| node_theme_ctx
node_analytics -->|"inside"| node_dashboard_shell
node_calendar_workspace -->|"renders"| node_calendar_ui
node_calendar_workspace -->|"fetches"| node_calendar_api
node_calendar_page -->|"renders"| node_calendar_ui
node_calendar_ui -->|"loads"| node_calendar_api
node_editorial_calendar -->|"fetches"| node_calendar_api
node_calendar_api -->|"proxies to"| node_stream_proxy
node_calendar_api -->|"targets"| node_post_gen_api
node_post_gen_api -->|"delegates"| node_text_gen_api
node_stream_proxy -->|"streams"| node_post_gen_api
node_admin_hub -->|"navigates"| node_content_admin
node_admin_hub -->|"navigates"| node_finance_admin
node_admin_hub -->|"navigates"| node_tech_admin
node_app_header -->|"reads"| node_sidebar_ctx
node_app_sidebar -->|"reads"| node_sidebar_ctx

click node_app_home "https://github.com/nasirsultan/shoulty-ai/blob/main/app/page.tsx"
click node_app_pricing "https://github.com/nasirsultan/shoulty-ai/blob/main/app/pricing/page.tsx"
click node_app_cases "https://github.com/nasirsultan/shoulty-ai/blob/main/app/case-studies/page.tsx"
click node_app_industry "https://github.com/nasirsultan/shoulty-ai/blob/main/app/for/[industry]/page.tsx"
click node_hero_section "https://github.com/nasirsultan/shoulty-ai/blob/main/components/HeroSection.tsx"
click node_footer "https://github.com/nasirsultan/shoulty-ai/blob/main/components/Footer.tsx"
click node_auth_signin "https://github.com/nasirsultan/shoulty-ai/blob/main/app/sign-in/page.tsx"
click node_auth_signup "https://github.com/nasirsultan/shoulty-ai/blob/main/app/sign-up/page.tsx"
click node_auth_flow "https://github.com/nasirsultan/shoulty-ai/blob/main/app/(auth)/profile-setup/page.tsx"
click node_signin_form "https://github.com/nasirsultan/shoulty-ai/blob/main/components/auth/SignInForm.tsx"
click node_nextauth "https://github.com/nasirsultan/shoulty-ai/blob/main/app/api/auth/[...nextauth]/route.ts"
click node_dashboard_shell "https://github.com/nasirsultan/shoulty-ai/blob/main/app/dashboards/page.tsx"
click node_app_header "https://github.com/nasirsultan/shoulty-ai/blob/main/layout/AppHeader.tsx"
click node_app_sidebar "https://github.com/nasirsultan/shoulty-ai/blob/main/layout/AppSidebar.tsx"
click node_analytics "https://github.com/nasirsultan/shoulty-ai/blob/main/app/dashboards/analytics/page.tsx"
click node_calendar_workspace "https://github.com/nasirsultan/shoulty-ai/blob/main/app/dashboards/calendar/page.tsx"
click node_calendar_page "https://github.com/nasirsultan/shoulty-ai/blob/main/app/calendar-dashboard/page.tsx"
click node_editorial_calendar "https://github.com/nasirsultan/shoulty-ai/blob/main/app/editorial-calendar/page.tsx"
click node_calendar_ui "https://github.com/nasirsultan/shoulty-ai/blob/main/components/calendar/Calendar.tsx"
click node_calendar_api "https://github.com/nasirsultan/shoulty-ai/blob/main/api/calendarApi.ts"
click node_text_gen_api "https://github.com/nasirsultan/shoulty-ai/blob/main/app/api/generator/texts/route.ts"
click node_post_gen_api "https://github.com/nasirsultan/shoulty-ai/blob/main/app/api/post-generator/generate/route.ts"
click node_stream_proxy "https://github.com/nasirsultan/shoulty-ai/blob/main/app/api/proxy/stream-posts/route.ts"
click node_admin_hub "https://github.com/nasirsultan/shoulty-ai/blob/main/app/admin/page.tsx"
click node_content_admin "https://github.com/nasirsultan/shoulty-ai/blob/main/app/content-admin/page.tsx"
click node_finance_admin "https://github.com/nasirsultan/shoulty-ai/blob/main/app/finance-admin/page.tsx"
click node_tech_admin "https://github.com/nasirsultan/shoulty-ai/blob/main/app/technical-admin/page.tsx"
click node_sidebar_ctx "https://github.com/nasirsultan/shoulty-ai/blob/main/context/SidebarContext.tsx"
click node_theme_ctx "https://github.com/nasirsultan/shoulty-ai/blob/main/context/ThemeContext.tsx"

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_home,node_app_pricing,node_app_cases,node_app_industry toneBlue
class node_auth_signin,node_auth_signup,node_auth_flow toneAmber
class node_dashboard_shell,node_analytics,node_calendar_workspace,node_calendar_page,node_editorial_calendar toneMint
class node_admin_hub,node_content_admin,node_finance_admin,node_tech_admin toneRose
class node_hero_section,node_footer,node_signin_form,node_nextauth,node_app_header,node_app_sidebar,node_calendar_ui,node_calendar_api,node_text_gen_api,node_post_gen_api,node_stream_proxy,node_sidebar_ctx,node_theme_ctx toneIndigo
```

## Components

### Public site

Marketing pages and SEO-focused public routes.

- [Home](https://github.com/nasirsultan/shoulty-ai/blob/main/app/page.tsx): route · Landing page for the public site. · `app/page.tsx`
- [Pricing](https://github.com/nasirsultan/shoulty-ai/blob/main/app/pricing/page.tsx): route · Pricing and conversion page. · `app/pricing/page.tsx`
- [Case studies](https://github.com/nasirsultan/shoulty-ai/blob/main/app/case-studies/page.tsx): route · Public proof and customer stories. · `app/case-studies/page.tsx`
- [Industry pages](https://github.com/nasirsultan/shoulty-ai/blob/main/app/for/[industry]/page.tsx): route · Dynamic industry landing pages. · `app/for/[industry]/page.tsx`

### Auth

Sign-in, sign-up, onboarding, and session handling.

- [Sign in](https://github.com/nasirsultan/shoulty-ai/blob/main/app/sign-in/page.tsx): auth route · Primary sign-in page. · `app/sign-in/page.tsx`
- [Sign up](https://github.com/nasirsultan/shoulty-ai/blob/main/app/sign-up/page.tsx): auth route · Primary sign-up page. · `app/sign-up/page.tsx`
- [Onboarding](https://github.com/nasirsultan/shoulty-ai/blob/main/app/(auth)/profile-setup/page.tsx): auth route group · Password reset, verification, and profile setup. · `app/(auth)/profile-setup/page.tsx`

### App workspace

Authenticated dashboards and calendar products.

- [Dashboard shell](https://github.com/nasirsultan/shoulty-ai/blob/main/app/dashboards/page.tsx): workspace route · Root authenticated workspace layout. · `app/dashboards/page.tsx`
- [Analytics](https://github.com/nasirsultan/shoulty-ai/blob/main/app/dashboards/analytics/page.tsx): workspace route · Dashboard analytics surface. · `app/dashboards/analytics/page.tsx`
- [Calendar](https://github.com/nasirsultan/shoulty-ai/blob/main/app/dashboards/calendar/page.tsx): workspace route · Dashboard calendar workspace. · `app/dashboards/calendar/page.tsx`
- [Calendar app](https://github.com/nasirsultan/shoulty-ai/blob/main/app/calendar-dashboard/page.tsx): product route · Standalone calendar dashboard page. · `app/calendar-dashboard/page.tsx`
- [Editorial calendar](https://github.com/nasirsultan/shoulty-ai/blob/main/app/editorial-calendar/page.tsx): product route · Editorial planning surface. · `app/editorial-calendar/page.tsx`

### Admin

Internal administrative surfaces.

- [Admin hub](https://github.com/nasirsultan/shoulty-ai/blob/main/app/admin/page.tsx): admin route · Top-level internal admin console. · `app/admin/page.tsx`
- [Content admin](https://github.com/nasirsultan/shoulty-ai/blob/main/app/content-admin/page.tsx): admin route · Content management surface. · `app/content-admin/page.tsx`
- [Finance admin](https://github.com/nasirsultan/shoulty-ai/blob/main/app/finance-admin/page.tsx): admin route · Financial admin surface. · `app/finance-admin/page.tsx`
- [Technical admin](https://github.com/nasirsultan/shoulty-ai/blob/main/app/technical-admin/page.tsx): admin route · Technical admin surface. · `app/technical-admin/page.tsx`

### Platform

Shared UI, state, API wrappers, and backend routes.

- [Hero section](https://github.com/nasirsultan/shoulty-ai/blob/main/components/HeroSection.tsx): marketing component · Core public-site presentation component. · `components/HeroSection.tsx`
- [Footer](https://github.com/nasirsultan/shoulty-ai/blob/main/components/Footer.tsx): marketing component · Shared public-site footer. · `components/Footer.tsx`
- [Auth form](https://github.com/nasirsultan/shoulty-ai/blob/main/components/auth/SignInForm.tsx): auth component · Reusable sign-in/sign-up UI. · `components/auth/SignInForm.tsx`
- [Auth API](https://github.com/nasirsultan/shoulty-ai/blob/main/app/api/auth/[...nextauth]/route.ts): route handler · NextAuth session and credential backend. · `app/api/auth/[...nextauth]/route.ts`
- [App header](https://github.com/nasirsultan/shoulty-ai/blob/main/layout/AppHeader.tsx): shell component · Shared dashboard header. · `layout/AppHeader.tsx`
- [App sidebar](https://github.com/nasirsultan/shoulty-ai/blob/main/layout/AppSidebar.tsx): shell component · Shared dashboard navigation. · `layout/AppSidebar.tsx`
- [Calendar UI](https://github.com/nasirsultan/shoulty-ai/blob/main/components/calendar/Calendar.tsx): product component · Calendar interaction and display layer. · `components/calendar/Calendar.tsx`
- [Calendar API](https://github.com/nasirsultan/shoulty-ai/blob/main/api/calendarApi.ts): client module · Typed client for calendar data. · `api/calendarApi.ts`
- [Text gen API](https://github.com/nasirsultan/shoulty-ai/blob/main/app/api/generator/texts/route.ts): route handler · Text generation backend endpoint. · `app/api/generator/texts/route.ts`
- [Post gen API](https://github.com/nasirsultan/shoulty-ai/blob/main/app/api/post-generator/generate/route.ts): route handler · Post generation and save endpoint. · `app/api/post-generator/generate/route.ts`
- [Stream proxy](https://github.com/nasirsultan/shoulty-ai/blob/main/app/api/proxy/stream-posts/route.ts): route handler · Streaming bridge for generated posts. · `app/api/proxy/stream-posts/route.ts`
- [Sidebar state](https://github.com/nasirsultan/shoulty-ai/blob/main/context/SidebarContext.tsx): context · Global sidebar open/close state. · `context/SidebarContext.tsx`
- [Theme state](https://github.com/nasirsultan/shoulty-ai/blob/main/context/ThemeContext.tsx): context · Global theme state. · `context/ThemeContext.tsx`

## Connections

- Home → Hero section: composes · Home page renders the main marketing hero.
- Home → Footer: composes · Public pages share the common footer.
- Pricing → Hero section: uses · Pricing page reuses marketing sections.
- Case studies → Hero section: uses · Case-study page uses shared marketing layout.
- Industry pages → Hero section: uses · Industry landing pages are built from shared sections.
- Sign in → Auth form: renders · Sign-in page is backed by custom auth UI.
- Sign up → Auth form: renders · Sign-up flow shares auth form components.
- Onboarding → Auth form: renders · Onboarding steps use the same auth UI layer.
- Auth form → Auth API: authenticates · Forms submit to the NextAuth backend.
- Dashboard shell → App header: uses · Workspace pages share the dashboard header.
- Dashboard shell → App sidebar: uses · Workspace pages share the dashboard sidebar.
- Dashboard shell → Sidebar state: depends on · Shell state is coordinated through context.
- Dashboard shell → Theme state: depends on · Shell theme toggles are centralized.
- Analytics → Dashboard shell: inside · Analytics lives within the authenticated workspace.
- Calendar → Calendar UI: renders · Calendar dashboard uses the dedicated calendar UI.
- Calendar → Calendar API: fetches · Calendar data is loaded through the typed client.
- Calendar app → Calendar UI: renders · Standalone calendar page uses the same UI component.
- Calendar UI → Calendar API: loads · Calendar UI reads and mutates calendar data via client APIs.
- Editorial calendar → Calendar API: fetches · Editorial planning reuses calendar data services.
- Calendar API → Stream proxy: proxies to · Client calls can be forwarded through streaming handlers.
- Calendar API → Post gen API: targets · Calendar workflows connect to generation endpoints.
- Post gen API → Text gen API: delegates · Post generation builds on text generation.
- Stream proxy → Post gen API: streams · Proxy routes support incremental generation and save flows.
- Admin hub → Content admin: navigates · Admin hub fans out to internal sub-consoles.
- Admin hub → Finance admin: navigates · Admin hub fans out to internal sub-consoles.
- Admin hub → Technical admin: navigates · Admin hub fans out to internal sub-consoles.
- App header → Sidebar state: reads · Header interacts with shared sidebar state.
- App sidebar → Sidebar state: reads · Sidebar state is managed centrally.
