How nasirsultan/shoulty-ai works
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: page.tsx Dashboard shell · calendarApi.ts Calendar API · SignInForm.tsx Auth form · HeroSection.tsx Hero section
Components 29
Public site
Marketing pages and SEO-focused public routes.
- Home · Landing page for the public site.
app/page.tsx - Pricing · Pricing and conversion page.
app/pricing/page.tsx - Case studies · Public proof and customer stories.
app/case-studies/page.tsx - Industry pages · Dynamic industry landing pages.
app/for/[industry]/page.tsx
Auth
Sign-in, sign-up, onboarding, and session handling.
- Sign in · Primary sign-in page.
app/sign-in/page.tsx - Sign up · Primary sign-up page.
app/sign-up/page.tsx - Onboarding · Password reset, verification, and profile setup.
app/(auth)/profile-setup/page.tsx
App workspace
Authenticated dashboards and calendar products.
- Dashboard shell · Root authenticated workspace layout.
app/dashboards/page.tsx - Analytics · Dashboard analytics surface.
app/dashboards/analytics/page.tsx - Calendar · Dashboard calendar workspace.
app/dashboards/calendar/page.tsx - Calendar app · Standalone calendar dashboard page.
app/calendar-dashboard/page.tsx - Editorial calendar · Editorial planning surface.
app/editorial-calendar/page.tsx
Admin
Internal administrative surfaces.
- Admin hub · Top-level internal admin console.
app/admin/page.tsx - Content admin · Content management surface.
app/content-admin/page.tsx - Finance admin · Financial admin surface.
app/finance-admin/page.tsx - Technical admin · Technical admin surface.
app/technical-admin/page.tsx
Platform
Shared UI, state, API wrappers, and backend routes.
- Hero section · Core public-site presentation component.
components/HeroSection.tsx - Footer · Shared public-site footer.
components/Footer.tsx - Auth form · Reusable sign-in/sign-up UI.
components/auth/SignInForm.tsx - Auth API · NextAuth session and credential backend.
app/api/auth/[...nextauth]/route.ts - App header · Shared dashboard header.
layout/AppHeader.tsx - App sidebar · Shared dashboard navigation.
layout/AppSidebar.tsx - Calendar UI · Calendar interaction and display layer.
components/calendar/Calendar.tsx - Calendar API · Typed client for calendar data.
api/calendarApi.ts - Text gen API · Text generation backend endpoint.
app/api/generator/texts/route.ts - Post gen API · Post generation and save endpoint.
app/api/post-generator/generate/route.ts - Stream proxy · Streaming bridge for generated posts.
app/api/proxy/stream-posts/route.ts - Sidebar state · Global sidebar open/close state.
context/SidebarContext.tsx - Theme state · Global theme state.
context/ThemeContext.tsx
Connections 28
- 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.