# mohamed-ehab-dev/store architecture

> Architecture diagram of the GitHub repository mohamed-ehab-dev/store, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mohamed-ehab-dev/store
- Repository: https://github.com/mohamed-ehab-dev/store

## Overview

1. This repository is a single Next.js App Router application that combines the public site, authenticated user areas, admin console, and all backend API routes in one codebase. It is not split into a separate frontend/backend service; the browser-facing UI and server-side request handling live under the same `app/` tree.

2. The application is organized by route groups:
   - `app/(main)` for marketing/content pages like homepage, pricing, blog, FAQs, templates, support, policies
   - `app/(auth)` for sign-in and registration
   - `app/(dashboard)` for logged-in end-user account pages
   - `app/(admin)` for staff/admin operations
   - `app/(user)` for user-specific utilities like favorites
   - `app/banned` and `app/not-found` for special states

3. The backend is a large REST-style API surface under `app/api/`. These handlers cover:
   - content domains: blogs, categories, FAQs, templates
   - account domains: users, favorites, preferences, profile/password changes
   - commerce/download flows: purchased templates, downloads
   - support/ticketing: tickets, messages, admin moderation
   - analytics/telemetry: tracking, stats, visitor records
   - moderation/admin operations: bulk update/delete, bans, logs, notifications

4. The central domain model layer lives in `lib/models/` and `lib/validations/`. This strongly suggests a database-backed architecture with schema models for entities like `User`, `Template`, `Order`, `Ticket`, `Message`, `Review`, `Blog`, `Category`, `FAQ`, `Notification`, `Visitor`, and log records. Request handlers appear to validate input first, then persist/query through these models.

5. Authentication and authorization are a major boundary. `lib/auth.ts`, `middleware/auth.ts`, `proxy.ts`, and the route-group layouts indicate role-based access control for public, authenticated, and admin-only areas. There are explicit flows for login/logout, registration, ban/unban, password changes, account deletion, and online/offline presence.

6. The main product domain appears to be a template marketplace/content platform. Public pages and APIs revolve around browsing templates, featured templates, search, downloads, reviews, and user favorites. The same domain is mirrored in the admin console for creating/editing templates, categories, blogs, and FAQs.

7. The support system is its own subsystem, with both user and admin views plus ticket-message endpoints. The presence of `Ticket`, `TicketMessage`, and client components for ticket details implies a conversational support workflow, likely with near-real-time updates. The `hooks/useSocket.ts` and `store/useSocketStore.ts` files reinforce a socket-based live communication layer.

8. Analytics and operational visibility are first-class. There are API routes and admin pages for analytics, visitor tracking, download logs, error logs, and support stats. `context/AnalyticsContext.tsx`, `hooks/useAnalyticsStats.ts`, and `store/useAnalyticsStore.ts` suggest telemetry is collected on the client and aggregated server-side for dashboards.

9. Media handling is integrated through Cloudinary. `lib/cloudinary.ts`, `app/api/cloudinary/sign/route.ts`, and `hooks/useCloudinaryUpload.ts` indicate signed uploads rather than direct file storage in the app. This is important for architecture because asset upload is delegated to an external service, while the app controls signing and metadata.

10. The UI is heavily componentized by domain and shared interaction patterns. `components/Admin`, `components/Dashboard`, `components/Support`, `components/home`, `components/singleTemplate`, and `components/shared` map closely to product areas, while `components/ui` contains reusable primitives. Most complex pages likely stitch together server-rendered route pages and client-side “Client” components for tables, forms, dialogs, and live interactions.

11. State management is split across React context and client stores. `context/UserContext.tsx` and `context/AnalyticsContext.tsx` provide app-wide context, while `store/useUserStore.ts`, `store/useAnalyticsStore.ts`, and `store/useSocketStore.ts` indicate local/global client state for auth, metrics, and realtime state. This reduces prop drilling across the large dashboard/admin surface.

12. There is a distinct SEO/content delivery layer. `app/robots.ts`, `app/sitemap.ts`, `components/SEO/StructuredData.tsx`, and markdown utilities support crawlable marketing pages and content-heavy pages like blog and templates. Static assets, fonts, videos, screenshots, and PWA files in `public/` suggest the public site is optimized for rich media and search visibility.

13. Operationally, the repo includes cache invalidation and refresh tooling. `actions/revalidateTag.ts` and the `/admin/refresh` page imply server-side cache/tag invalidation to keep content lists and detail pages fresh after edits. This matters because many admin actions likely need to propagate immediately to public listings.

14. Supporting infrastructure is bundled into the app: image utilities, markdown helpers, notification utilities, payment helpers, and a broad set of validations. The overall architecture is a modular monolith with clear domain boundaries, server-rendered pages for most screens, API routes for data mutation/query, and a few external dependencies for media and live support.

Main entry points: [`lib/models`](https://github.com/mohamed-ehab-dev/store/tree/main/lib/models) (Domain models), [`components`](https://github.com/mohamed-ehab-dev/store/tree/main/components) (Domain UI), [`lib/auth.ts`](https://github.com/mohamed-ehab-dev/store/blob/main/lib/auth.ts) (Auth boundary), [`app/api/user`](https://github.com/mohamed-ehab-dev/store/tree/main/app/api/user) (Account API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_app["App routes"]
  node_n_app_main["Public site<br/>Next.js routes"]
  node_n_app_auth["Auth pages<br/>Next.js routes"]
  node_n_app_dashboard["Dashboard<br/>Next.js routes"]
  node_n_app_admin["Admin console<br/>Next.js routes"]
  node_n_app_user["User tools<br/>Next.js routes"]
  node_n_app_special["Special states<br/>Next.js routes"]
end

subgraph group_g_api["API surface"]
  node_n_api_user["Account API<br/>REST handlers"]
  node_n_api_content["Content API<br/>REST handlers"]
  node_n_api_template["Template API<br/>REST handlers"]
  node_n_api_support["Support API<br/>REST handlers"]
  node_n_api_admin["Admin API<br/>REST handlers"]
  node_n_api_telemetry["Telemetry API<br/>REST handlers"]
  node_n_api_media["Media signing<br/>Cloudinary API"]
end

subgraph group_g_core["Core domain"]
  node_n_core_auth{{"Auth boundary<br/>RBAC + middleware<br/>[auth.ts]"}}
  node_n_core_models[("Domain models<br/>DB models")]
  node_n_core_validations["Validation layer<br/>Schema validation"]
  node_n_core_db[("Database<br/>Persistence<br/>[database.ts]")]
  node_n_core_cloudinary{{"Cloudinary<br/>External media<br/>[cloudinary.ts]"}}
  node_n_core_payments["Payments<br/>Commerce helpers<br/>[payments.ts]"]
end

subgraph group_g_ui["Client layer"]
  node_n_ui_components["Domain UI<br/>React components"]
  node_n_ui_state["Client state<br/>Context + stores"]
  node_n_ui_hooks["Client hooks"]
end

node_n_app_main -->|"renders"| node_n_ui_components
node_n_app_auth -->|"guards"| node_n_core_auth
node_n_app_auth -->|"uses forms"| node_n_ui_components
node_n_app_dashboard -->|"protects"| node_n_core_auth
node_n_app_dashboard -->|"renders"| node_n_ui_components
node_n_app_admin -->|"restricts"| node_n_core_auth
node_n_app_admin -->|"renders"| node_n_ui_components
node_n_app_user -->|"protects"| node_n_core_auth
node_n_app_user -->|"renders"| node_n_ui_components
node_n_api_user -->|"authenticates"| node_n_core_auth
node_n_api_user -->|"validates"| node_n_core_validations
node_n_api_user -->|"persists"| node_n_core_models
node_n_api_content -->|"queries"| node_n_core_models
node_n_api_content -->|"validates"| node_n_core_validations
node_n_api_template -->|"reads/writes"| node_n_core_models
node_n_api_template -->|"supports"| node_n_core_payments
node_n_api_support -->|"threads"| node_n_core_models
node_n_api_support -->|"realtime"| node_n_ui_hooks
node_n_api_admin -->|"administers"| node_n_core_models
node_n_api_admin -->|"restricts"| node_n_core_auth
node_n_api_telemetry -->|"collects"| node_n_ui_state
node_n_api_telemetry -->|"aggregates"| node_n_core_models
node_n_api_media -->|"signs"| node_n_core_cloudinary
node_n_ui_components -->|"consumes"| node_n_ui_state
node_n_ui_hooks -->|"uploads"| node_n_core_cloudinary
node_n_core_models -->|"uses"| node_n_core_db
node_n_core_validations -.->|"fronts"| node_n_api_user
node_n_core_validations -.->|"fronts"| node_n_api_admin

click node_n_app_main "https://github.com/mohamed-ehab-dev/store/tree/main/app/(main)"
click node_n_app_auth "https://github.com/mohamed-ehab-dev/store/tree/main/app/(auth)"
click node_n_app_dashboard "https://github.com/mohamed-ehab-dev/store/tree/main/app/(dashboard)"
click node_n_app_admin "https://github.com/mohamed-ehab-dev/store/tree/main/app/(admin)"
click node_n_app_user "https://github.com/mohamed-ehab-dev/store/tree/main/app/(user)"
click node_n_app_special "https://github.com/mohamed-ehab-dev/store/tree/main/app/banned"
click node_n_api_user "https://github.com/mohamed-ehab-dev/store/tree/main/app/api/user"
click node_n_api_content "https://github.com/mohamed-ehab-dev/store/tree/main/app/api"
click node_n_api_template "https://github.com/mohamed-ehab-dev/store/tree/main/app/api/template"
click node_n_api_support "https://github.com/mohamed-ehab-dev/store/tree/main/app/api/support"
click node_n_api_admin "https://github.com/mohamed-ehab-dev/store/tree/main/app/api/admin"
click node_n_api_telemetry "https://github.com/mohamed-ehab-dev/store/tree/main/app/api/analytics"
click node_n_api_media "https://github.com/mohamed-ehab-dev/store/tree/main/app/api/cloudinary/sign"
click node_n_core_auth "https://github.com/mohamed-ehab-dev/store/blob/main/lib/auth.ts"
click node_n_core_models "https://github.com/mohamed-ehab-dev/store/tree/main/lib/models"
click node_n_core_validations "https://github.com/mohamed-ehab-dev/store/tree/main/lib/validations"
click node_n_core_db "https://github.com/mohamed-ehab-dev/store/blob/main/lib/database.ts"
click node_n_core_cloudinary "https://github.com/mohamed-ehab-dev/store/blob/main/lib/cloudinary.ts"
click node_n_core_payments "https://github.com/mohamed-ehab-dev/store/blob/main/lib/payments.ts"
click node_n_ui_components "https://github.com/mohamed-ehab-dev/store/tree/main/components"
click node_n_ui_state "https://github.com/mohamed-ehab-dev/store/tree/main/context"
click node_n_ui_hooks "https://github.com/mohamed-ehab-dev/store/tree/main/hooks"

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_n_app_main,node_n_app_auth,node_n_app_dashboard,node_n_app_admin,node_n_app_user,node_n_app_special toneBlue
class node_n_api_user,node_n_api_content,node_n_api_template,node_n_api_support,node_n_api_admin,node_n_api_telemetry,node_n_api_media toneAmber
class node_n_core_auth,node_n_core_models,node_n_core_validations,node_n_core_db,node_n_core_cloudinary,node_n_core_payments toneMint
class node_n_ui_components,node_n_ui_state,node_n_ui_hooks toneRose
```

## Components

### App routes

Next.js route groups and special pages

- [Public site](https://github.com/mohamed-ehab-dev/store/tree/main/app/(main)): Next.js routes · Marketing, content, and product browsing pages · `app/(main)`
- [Auth pages](https://github.com/mohamed-ehab-dev/store/tree/main/app/(auth)): Next.js routes · Sign-in and registration flows · `app/(auth)`
- [Dashboard](https://github.com/mohamed-ehab-dev/store/tree/main/app/(dashboard)): Next.js routes · Authenticated user account area · `app/(dashboard)`
- [Admin console](https://github.com/mohamed-ehab-dev/store/tree/main/app/(admin)): Next.js routes · Staff operations and management screens · `app/(admin)`
- [User tools](https://github.com/mohamed-ehab-dev/store/tree/main/app/(user)): Next.js routes · User-specific utilities like favorites · `app/(user)`
- [Special states](https://github.com/mohamed-ehab-dev/store/tree/main/app/banned): Next.js routes · Banned and not-found handling · `app/banned`

### API surface

REST handlers organized by domain

- [Account API](https://github.com/mohamed-ehab-dev/store/tree/main/app/api/user): REST handlers · Login, registration, profile, presence, favorites, preferences · `app/api/user`
- [Content API](https://github.com/mohamed-ehab-dev/store/tree/main/app/api): REST handlers · Blogs, categories, FAQs, templates, search, featured content · `app/api`
- [Template API](https://github.com/mohamed-ehab-dev/store/tree/main/app/api/template): REST handlers · Template detail, download, search, stats, and listing endpoints · `app/api/template`
- [Support API](https://github.com/mohamed-ehab-dev/store/tree/main/app/api/support): REST handlers · Tickets, messages, and support workflows · `app/api/support`
- [Admin API](https://github.com/mohamed-ehab-dev/store/tree/main/app/api/admin): REST handlers · Moderation, bulk ops, analytics, logs, users, visitors · `app/api/admin`
- [Telemetry API](https://github.com/mohamed-ehab-dev/store/tree/main/app/api/analytics): REST handlers · Client tracking and aggregated stats · `app/api/analytics`
- [Media signing](https://github.com/mohamed-ehab-dev/store/tree/main/app/api/cloudinary/sign): Cloudinary API · Signed upload flow for external media storage · `app/api/cloudinary/sign`

### Core domain

Models, validation, auth, and infrastructure

- [Auth boundary](https://github.com/mohamed-ehab-dev/store/blob/main/lib/auth.ts): RBAC + middleware · Session, role checks, proxy, and route protection · `lib/auth.ts`
- [Domain models](https://github.com/mohamed-ehab-dev/store/tree/main/lib/models): DB models · Persistent entities for users, templates, tickets, logs, and content · `lib/models`
- [Validation layer](https://github.com/mohamed-ehab-dev/store/tree/main/lib/validations): Schema validation · Input schemas for API and form handling · `lib/validations`
- [Database](https://github.com/mohamed-ehab-dev/store/blob/main/lib/database.ts): Persistence · Shared database connection and query access · `lib/database.ts`
- [Cloudinary](https://github.com/mohamed-ehab-dev/store/blob/main/lib/cloudinary.ts): External media · Image and asset storage outside the app · `lib/cloudinary.ts`
- [Payments](https://github.com/mohamed-ehab-dev/store/blob/main/lib/payments.ts): Commerce helpers · Purchase and download-related business support · `lib/payments.ts`

### Client layer

Shared UI, contexts, stores, and domain components

- [Domain UI](https://github.com/mohamed-ehab-dev/store/tree/main/components): React components · Admin, dashboard, support, home, templates, and shared UI · `components`
- [Client state](https://github.com/mohamed-ehab-dev/store/tree/main/context): Context + stores · User, analytics, and socket state across the app · `context`
- [Client hooks](https://github.com/mohamed-ehab-dev/store/tree/main/hooks): Hooks · Socket, analytics, and upload integrations · `hooks`

## Connections

- Public site → Domain UI: renders · Public pages compose shared and domain UI
- Auth pages → Auth boundary: guards · Auth pages rely on shared identity and session logic
- Auth pages → Domain UI: uses forms · Sign-in and registration screens use form components
- Dashboard → Auth boundary: protects · Dashboard routes require authenticated access
- Dashboard → Domain UI: renders · Dashboard screens use dashboard-specific components
- Admin console → Auth boundary: restricts · Admin routes are role-protected
- Admin console → Domain UI: renders · Admin console uses admin client components and tables
- User tools → Auth boundary: protects · User utility routes require login
- User tools → Domain UI: renders · Favorites and similar utilities use shared UI
- Account API → Auth boundary: authenticates · User endpoints handle login, logout, and account actions
- Account API → Validation layer: validates · Account mutations are schema-validated
- Account API → Domain models: persists · User state, favorites, and preferences use domain models
- Content API → Domain models: queries · Content endpoints read blogs, categories, FAQs, and templates
- Content API → Validation layer: validates · Content mutations validate payloads
- Template API → Domain models: reads/writes · Template browsing, stats, and download flows use models
- Template API → Payments: supports · Purchase/download flows connect to commerce helpers
- Support API → Domain models: threads · Tickets and messages are stored as domain records
- Support API → Client hooks: realtime · Support conversations pair with socket-based live updates
- Admin API → Domain models: administers · Moderation and bulk operations act on persisted entities
- Admin API → Auth boundary: restricts · Admin APIs are authorization-bound
- Telemetry API → Client state: collects · Telemetry is captured from client state and context
- Telemetry API → Domain models: aggregates · Stats and visitor records are stored server-side
- Media signing → Cloudinary: signs · Uploads are delegated to Cloudinary via signed requests
- Domain UI → Client state: consumes · UI components depend on shared app state
- Client hooks → Cloudinary: uploads · Upload hooks integrate with Cloudinary signing
- Domain models → Database: uses · Models are backed by the shared database connection
- Validation layer → Account API: fronts · Validation is the first boundary before persistence and actions
- Validation layer → Admin API: fronts · Admin mutations are validated before model access
