# connect2local247/development architecture

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

- Interactive diagram: https://gitdiagram.com/connect2local247/development
- Repository: https://github.com/connect2local247/development

## Overview

1. This is a Next.js App Router application that combines a public marketing/portfolio site with a logged-in admin/user portal. The UI lives under `src/app`, while almost all business operations are exposed through route handlers under `src/app/api`.

2. The app has two main surfaces:
   - Public-facing pages: home, about, services, portfolio, projects, blogs, case studies, contact, terms, and payment-related views.
   - Authenticated dashboard areas: `/user/[role]` with management screens for users, clients, projects, payments, receipts, refunds, requests, notifications, inbox, CMS, and role-permission administration.

3. The API layer is organized by domain rather than by generic CRUD. Route groups such as `auth`, `dashboard`, `project-management`, `payment-management`, `resource-management`, `role-permission`, `notification`, `client`, `request`, `upload`, `webhook`, and `cms` map directly to business capabilities. Most endpoints follow an `[action]` and optional `[data]` pattern, suggesting a command-style API design rather than a purely RESTful one.

4. Underneath the route handlers is a server-side application layer in `src/server`. It is split into:
   - `module/*`: domain controllers and module configs
   - `controller/*`: higher-level controllers
   - `service/*`: orchestration and workflow logic
   - `provider/*`: external integrations
   - `config/*`: environment, middleware, payment, upload, Firebase, GraphQL, templates, and model wiring

5. Persistence is handled by Prisma with a fairly rich relational schema. The migration history shows evolving models for users, clients/POs, projects, project attributes, technologies, links, payments, payment orders, receipts, refunds, currencies, payment methods/types, notifications, and role/permission entities. This is the core data store for the portal and the admin workflows.

6. The domain model is centered around a few major subsystems:
   - Project management: project records, attributes, technologies, links, media, status, and client/project associations.
   - Payment management: payment requests, payment orders, receipts, refunds, currencies, methods, and payment types.
   - Access control: roles, permissions, modules, and assignment screens.
   - Content management: editable pages and sections for the marketing site.
   - Notifications/inbox: cross-cutting messaging around payments, projects, and user actions.

7. External integrations materially shape the architecture:
   - Razorpay for payment processing and payment/order lifecycle.
   - Cloudinary for media uploads and asset storage.
   - Firebase for messaging/push and admin permission support.
   - Mail delivery and templated emails for OTP, welcome, payment, refund, and invoice flows.
   - GraphQL is present for page/content retrieval and selected backend workflows, alongside the route-handler API.

8. Data flow is typically: UI page/component → client hook/store/API helper → Next.js route handler → server module/controller/service → Prisma/database and/or external provider. The `src/config/api` and `src/hooks/*` folders provide the client-side request and state abstraction, while `src/server/lib/*` and `src/lib/*` provide shared validation, formatting, serialization, and response/error handling.

9. The frontend is highly componentized. `src/component` contains reusable UI primitives, forms, tables, cards, views, loaders, layouts, modals, and domain-specific sections. The codebase separates:
   - generic UI building blocks
   - domain forms for projects, payments, users, clients, and role-permission
   - read-only views for project/payment/user detail screens
   - layout shells for public site, auth pages, dashboard, and request/payment flows

10. State management is split by domain and UI concern. The `src/config/store` area contains stores for payment, project, request, portfolio, CMS/page editor, theme, users, and role-permission. This suggests the app uses client-side state for complex multi-step workflows such as editing projects, handling payments, and managing CMS content.

11. Validation and data shaping are important boundaries. Schema definitions live in `src/lib/schema`, with supporting types, patterns, formatters, serializers, and helpers spread across `src/lib` and `src/server/lib`. This indicates input validation and output normalization happen close to the domain boundary before data reaches Prisma or external services.

12. There is also a content/SEO/operational layer:
   - sitemap generation and `next-sitemap.config.js`
   - `public/firebase-messaging-sw.js` for push notifications
   - static assets in `public/images`
   - Google site verification file
   - CMS pages for editing public content
   These suggest the repository is not just an internal tool, but also powers a public portfolio/agency site with operational back-office features.

13. The main architectural boundary to preserve in a diagram is between presentation, API orchestration, and domain infrastructure. The UI should be shown as consuming backend capabilities through Next.js route handlers, while server modules should be shown as the canonical business layer coordinating database, payment, upload, notification, and messaging integrations.

Main entry points: [`src/server/module`](https://github.com/connect2local247/development/tree/main/src/server/module) (Business Modules), [`src/server/service`](https://github.com/connect2local247/development/tree/main/src/server/service) (Services), [`src/server/provider`](https://github.com/connect2local247/development/tree/main/src/server/provider) (Providers), [`src/app/api`](https://github.com/connect2local247/development/tree/main/src/app/api) (Route Handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_public_site["Public Site<br/>next app"]
  node_auth_pages["Auth Pages<br/>next app"]
  node_dashboard_ui["Dashboard UI<br/>next app"]
end

subgraph group_api["API Layer"]
  node_api_routes["Route Handlers"]
  node_client_api["Client API<br/>request helpers"]
  node_client_state["Client State<br/>zustand stores"]
  node_graphql_api["GraphQL API"]
  node_cms_api["CMS API<br/>content endpoints"]
end

subgraph group_server["Server Domain"]
  node_server_modules["Business Modules<br/>domain modules"]
  node_server_controllers["Controllers<br/>orchestration"]
  node_server_services["Services<br/>workflow layer"]
  node_server_providers["Providers<br/>integrations"]
  node_server_config["Server Config<br/>runtime config"]
  node_validation_lib["Validation & Lib<br/>schemas and helpers"]
end

subgraph group_data["Data & Integrations"]
  node_prisma_db[("Prisma DB<br/>relational schema<br/>[schema.prisma]")]
  node_razorpay(("Razorpay<br/>payment gateway"))
  node_cloudinary(("Cloudinary<br/>media storage<br/>[cloudinary.ts]"))
  node_firebase(("Firebase<br/>messaging/auth infra<br/>[firebase.ts]"))
  node_mailer["Mail Templates<br/>email delivery"]
end

node_public_site -->|"fetches data"| node_client_api
node_auth_pages -->|"auth requests"| node_client_api
node_dashboard_ui -->|"portal actions"| node_client_api
node_dashboard_ui -->|"stores state"| node_client_state
node_client_api -->|"calls"| node_api_routes
node_client_state -->|"mutates via API"| node_api_routes
node_api_routes -->|"dispatches"| node_server_modules
node_server_modules -->|"coordinates"| node_server_controllers
node_server_controllers -->|"runs workflows"| node_server_services
node_server_services -->|"persists"| node_prisma_db
node_server_services -->|"integrates"| node_server_providers
node_server_providers -->|"payments"| node_razorpay
node_server_providers -->|"uploads"| node_cloudinary
node_server_providers -->|"messaging"| node_firebase
node_server_services -->|"emails"| node_mailer
node_server_modules -->|"depends on"| node_server_config
node_server_config -->|"shared boundary"| node_validation_lib
node_api_routes -->|"content query"| node_graphql_api
node_cms_api -->|"content ops"| node_server_modules
node_graphql_api -->|"resolves data"| node_prisma_db
node_server_modules -->|"validates"| node_validation_lib

click node_public_site "https://github.com/connect2local247/development/tree/main/src/app"
click node_auth_pages "https://github.com/connect2local247/development/tree/main/src/app/auth"
click node_dashboard_ui "https://github.com/connect2local247/development/tree/main/src/app/user/[role]"
click node_api_routes "https://github.com/connect2local247/development/tree/main/src/app/api"
click node_client_api "https://github.com/connect2local247/development/tree/main/src/config/api"
click node_client_state "https://github.com/connect2local247/development/tree/main/src/config/store"
click node_server_modules "https://github.com/connect2local247/development/tree/main/src/server/module"
click node_server_controllers "https://github.com/connect2local247/development/tree/main/src/server/controllers"
click node_server_services "https://github.com/connect2local247/development/tree/main/src/server/service"
click node_server_providers "https://github.com/connect2local247/development/tree/main/src/server/provider"
click node_server_config "https://github.com/connect2local247/development/tree/main/src/server/config"
click node_validation_lib "https://github.com/connect2local247/development/tree/main/src/lib"
click node_graphql_api "https://github.com/connect2local247/development/tree/main/src/graphql"
click node_cms_api "https://github.com/connect2local247/development/tree/main/src/app/api/cms"
click node_prisma_db "https://github.com/connect2local247/development/blob/main/prisma/schema.prisma"
click node_cloudinary "https://github.com/connect2local247/development/blob/main/src/config/cloudinary/cloudinary.ts"
click node_firebase "https://github.com/connect2local247/development/blob/main/src/config/firebase/firebase.ts"
click node_mailer "https://github.com/connect2local247/development/tree/main/src/server/templates"

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_public_site,node_auth_pages,node_dashboard_ui toneBlue
class node_api_routes,node_client_api,node_client_state,node_graphql_api,node_cms_api toneAmber
class node_server_modules,node_server_controllers,node_server_services,node_server_providers,node_server_config,node_validation_lib toneMint
class node_prisma_db,node_razorpay,node_cloudinary,node_firebase,node_mailer toneRose
```

## Components

### Presentation

Public site, auth, and dashboard surfaces rendered by Next.js App Router.

- [Public Site](https://github.com/connect2local247/development/tree/main/src/app): next app · Marketing and portfolio pages such as home, about, services, projects, blogs, case studies, contact, and terms. · `src/app`
- [Auth Pages](https://github.com/connect2local247/development/tree/main/src/app/auth): next app · Login, OTP verification, password recovery, and related authentication screens. · `src/app/auth`
- [Dashboard UI](https://github.com/connect2local247/development/tree/main/src/app/user/[role]): next app · Role-scoped portal for users, clients, projects, payments, receipts, refunds, requests, notifications, inbox, CMS, and access control. · `src/app/user/[role]`

### API Layer

Route handlers and client-side request/state adapters.

- [Route Handlers](https://github.com/connect2local247/development/tree/main/src/app/api): next route handlers · Domain-organized App Router API endpoints using action/data command-style routes. · `src/app/api`
- [Client API](https://github.com/connect2local247/development/tree/main/src/config/api): request helpers · Frontend endpoint definitions, API client setup, and query handler provider used by hooks and stores. · `src/config/api`
- [Client State](https://github.com/connect2local247/development/tree/main/src/config/store): zustand stores · Domain and UI stores for payments, projects, requests, CMS page editing, users, theme, and role-permission workflows. · `src/config/store`
- [GraphQL API](https://github.com/connect2local247/development/tree/main/src/graphql): graphql · Schema and resolvers for page/content retrieval and selected backend workflows. · `src/graphql`
- [CMS API](https://github.com/connect2local247/development/tree/main/src/app/api/cms): content endpoints · API surface for editable site pages and sections. · `src/app/api/cms`

### Server Domain

Canonical business logic, orchestration, and integration boundary.

- [Business Modules](https://github.com/connect2local247/development/tree/main/src/server/module): domain modules · Primary server-side domain controllers grouped by auth, dashboard, projects, payments, notifications, uploads, users, webhook, and access control. · `src/server/module`
- [Controllers](https://github.com/connect2local247/development/tree/main/src/server/controllers): orchestration · Higher-level controllers that expose domain operations and coordinate request handling. · `src/server/controllers`
- [Services](https://github.com/connect2local247/development/tree/main/src/server/service): workflow layer · Cross-entity business workflows, especially payment and notification orchestration. · `src/server/service`
- [Providers](https://github.com/connect2local247/development/tree/main/src/server/provider): integrations · Shared integration layer for external systems and infrastructure adapters. · `src/server/provider`
- [Server Config](https://github.com/connect2local247/development/tree/main/src/server/config): runtime config · Environment, middleware, GraphQL, Firebase, mailer, payment, upload, and model wiring. · `src/server/config`
- [Validation & Lib](https://github.com/connect2local247/development/tree/main/src/lib): schemas and helpers · Shared schemas, serializers, formatters, handlers, and utility code that shape input and output boundaries. · `src/lib`

### Data & Integrations

Persistence, external services, and operational assets.

- [Prisma DB](https://github.com/connect2local247/development/blob/main/prisma/schema.prisma): relational schema · Central relational persistence for users, projects, payments, receipts, refunds, notifications, roles, permissions, and content-related entities. · `prisma/schema.prisma`
- **Razorpay**: payment gateway · External payment processing and order lifecycle integration.
- [Cloudinary](https://github.com/connect2local247/development/blob/main/src/config/cloudinary/cloudinary.ts): media storage · Asset upload and media storage integration. · `src/config/cloudinary/cloudinary.ts`
- [Firebase](https://github.com/connect2local247/development/blob/main/src/config/firebase/firebase.ts): messaging/auth infra · Push messaging and admin permission support integration. · `src/config/firebase/firebase.ts`
- [Mail Templates](https://github.com/connect2local247/development/tree/main/src/server/templates): email delivery · Templated OTP, welcome, payment, refund, invoice, and contact email flows. · `src/server/templates`

## Connections

- Public Site → Client API: fetches data · Public pages consume API helpers and query hooks for dynamic content.
- Auth Pages → Client API: auth requests · Authentication screens submit through shared client API helpers.
- Dashboard UI → Client API: portal actions · Dashboard screens call domain-specific endpoint helpers.
- Dashboard UI → Client State: stores state · Complex portal workflows rely on domain client stores.
- Client API → Route Handlers: calls · Client-side helpers invoke Next.js route handlers.
- Client State → Route Handlers: mutates via API · Stores coordinate CRUD and command flows through route handlers.
- Route Handlers → Business Modules: dispatches · Route handlers delegate domain work to server modules.
- Business Modules → Controllers: coordinates · Modules reuse controllers for higher-level orchestration.
- Controllers → Services: runs workflows · Controllers hand off to services for multi-step business logic.
- Services → Prisma DB: persists · Services read and write the relational schema.
- Services → Providers: integrates · Services call external adapters through the provider layer.
- Providers → Razorpay: payments · Payment workflows use Razorpay for orders and settlement.
- Providers → Cloudinary: uploads · Media workflows store assets in Cloudinary.
- Providers → Firebase: messaging · Notifications and push flows use Firebase services.
- Services → Mail Templates: emails · Business events render and send templated mail.
- Business Modules → Server Config: depends on · Modules use shared runtime configuration and middleware wiring.
- Server Config → Validation & Lib: shared boundary · Configuration and handlers rely on shared schemas, formatting, and error handling.
- Route Handlers → GraphQL API: content query · Selected endpoints expose GraphQL-backed page and section retrieval.
- CMS API → Business Modules: content ops · CMS endpoints route page editing operations into server modules.
- GraphQL API → Prisma DB: resolves data · GraphQL resolvers source content from the database layer.
- Business Modules → Validation & Lib: validates · Domain modules validate and normalize inputs and outputs.
