# sharan-2686/cardcraft architecture

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

- Interactive diagram: https://gitdiagram.com/sharan-2686/cardcraft
- Repository: https://github.com/sharan-2686/cardcraft

## Overview

#### Purpose and Shape
CardConnect is a digital business-card platform with authentication, card creation/viewing, administrative management, QR, widget, and email-signature experiences. It has two independently packaged layers: an Express-style Node backend in `backend/` and a Next.js frontend in `next-app/`. A separate nested Vite client also exists under `next-app/CardConnect/CardConnect/client/`, likely an older or parallel frontend.

#### Runtime Entry Points
- Backend service starts from `backend/server.js`, with persistence initialization in `backend/db.js`.
- The primary UI is a Next.js App Router application rooted at `next-app/app/layout.tsx` and `next-app/app/page.tsx`.
- Client-side identity state is provided through `next-app/app/context/AuthContext.tsx`.
- The nested Vite application enters through `next-app/CardConnect/CardConnect/client/src/main.jsx` and `next-app/CardConnect/CardConnect/client/src/App.jsx`; its relationship to the Next app is not established by the repository tree.

#### API and Authentication Boundary
The backend exposes route groups for authentication, cards, and administration:
- `backend/authRoutes.js` delegates identity actions to `backend/authController.js`.
- `backend/cardRoutes.js` delegates card operations to `backend/cardController.js`.
- `backend/adminRoutes.js` delegates privileged operations to `backend/adminController.js`.
- `backend/authMiddleware.js` is the authorization boundary protecting routes or controller operations. Frontend pages and `AuthContext.tsx` are the likely consumers of these API endpoints.

#### Domain Persistence
The core persisted entities are users and cards:
- `backend/User.js`
- `backend/Card.js`
- `backend/db.js`

Controllers form the application layer between HTTP requests and these domain models. Card identity is surfaced publicly through the dynamic route `next-app/app/card/[id]/page.tsx`, with associated presentation styling in `next-app/app/card/[id]/card-view.css`.

#### Frontend Product Flows
The Next.js app organizes major user workflows as route-level screens:
- Login: `next-app/app/login/page.tsx`
- Authenticated dashboard: `next-app/app/dashboard/page.tsx`
- Card authoring: `next-app/app/create-card/page.tsx`
- Public/specific card viewing: `next-app/app/card/[id]/page.tsx`
- Administration: `next-app/app/admin/page.tsx`

Additional output and sharing surfaces are `next-app/app/qr/page.tsx`, `next-app/app/widgets/page.tsx`, and `next-app/app/email-signatures/page.tsx`. These likely derive from card data but their backend integration is not visible in the tree.

#### Email and External Delivery
Email handling is isolated behind `backend/emailController.js`, separating outbound email behavior from identity, card, and admin controllers. The specific provider, credentials, delivery trigger, and queueing model cannot be determined from the supplied files.

#### UI Composition and Assets
Shared page chrome and visual primitives are centralized in:
- `next-app/components/Header.tsx`
- `next-app/components/Footer.tsx`
- `next-app/components/ui/`

Global styling begins at `next-app/app/globals.css`; route-specific card and creation styles live beside their routes. Video/media assets are served from `next-app/public/`, while the parallel Vite client maintains its own assets under `next-app/CardConnect/CardConnect/client/src/assets/`.

Main entry points: [`backend/cardRoutes.js`](https://github.com/sharan-2686/cardcraft/blob/main/backend/cardRoutes.js) (Card routes), [`backend/authRoutes.js`](https://github.com/sharan-2686/cardcraft/blob/main/backend/authRoutes.js) (Auth routes), [`backend/server.js`](https://github.com/sharan-2686/cardcraft/blob/main/backend/server.js) (Backend server), [`backend/adminRoutes.js`](https://github.com/sharan-2686/cardcraft/blob/main/backend/adminRoutes.js) (Admin routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Node backend"]
  node_server["Backend server<br/>Express entry point<br/>[server.js]"]
  node_db[("Database initialization<br/>persistence setup<br/>[db.js]")]
  node_auth_routes["Auth routes<br/>HTTP routes<br/>[authRoutes.js]"]
  node_card_routes["Card routes<br/>HTTP routes<br/>[cardRoutes.js]"]
  node_admin_routes["Admin routes<br/>HTTP routes<br/>[adminRoutes.js]"]
  node_auth_middleware{{"Authorization middleware<br/>auth boundary<br/>[authMiddleware.js]"}}
  node_auth_controller["Auth controller<br/>application controller<br/>[authController.js]"]
  node_card_controller["Card controller<br/>application controller<br/>[cardController.js]"]
  node_admin_controller["Admin controller<br/>application controller<br/>[adminController.js]"]
  node_email_controller["Email controller<br/>outbound delivery<br/>[emailController.js]"]
  node_user_model["User model<br/>persisted entity<br/>[User.js]"]
  node_card_model["Card model<br/>persisted entity<br/>[Card.js]"]
end

subgraph group_next["Next.js app"]
  node_next_shell["App shell<br/>Next App Router<br/>[layout.tsx]"]
  node_home["Home page<br/>route screen<br/>[page.tsx]"]
  node_auth_context["Auth context<br/>client identity state<br/>[AuthContext.tsx]"]
  node_account_flows["Login and dashboard<br/>route screens<br/>[page.tsx]"]
  node_card_authoring["Card authoring<br/>route screen<br/>[page.tsx]"]
  node_public_card["Public card view<br/>dynamic route<br/>[page.tsx]"]
  node_admin_ui["Admin page<br/>route screen<br/>[page.tsx]"]
  node_sharing_surfaces["QR, widgets and signatures<br/>output route screens<br/>[page.tsx]"]
  node_shared_ui["Shared UI chrome<br/>components<br/>[Header.tsx]"]
end

subgraph group_vite["Parallel Vite client"]
  node_vite_entry["Vite entry<br/>client entry point<br/>[main.jsx]"]
  node_vite_app["Vite app<br/>client root<br/>[App.jsx]"]
end

node_server -->|"initializes"| node_db
node_server -->|"mounts"| node_auth_routes
node_server -->|"mounts"| node_card_routes
node_server -->|"mounts"| node_admin_routes
node_auth_routes -->|"uses"| node_auth_middleware
node_card_routes -->|"uses"| node_auth_middleware
node_admin_routes -->|"uses"| node_auth_middleware
node_auth_routes -->|"delegates to"| node_auth_controller
node_card_routes -->|"delegates to"| node_card_controller
node_admin_routes -->|"delegates to"| node_admin_controller
node_auth_controller -->|"reads and writes"| node_user_model
node_card_controller -->|"reads and writes"| node_card_model
node_admin_controller -->|"manages"| node_user_model
node_admin_controller -->|"manages"| node_card_model
node_email_controller -.->|"uses recipient identity"| node_user_model
node_next_shell -->|"hosts"| node_home
node_next_shell -->|"provides"| node_auth_context
node_next_shell -->|"composes"| node_shared_ui
node_auth_context -.->|"consumes API"| node_auth_routes
node_account_flows -.->|"authenticates via"| node_auth_routes
node_card_authoring -.->|"creates cards via"| node_card_routes
node_public_card -.->|"loads card via"| node_card_routes
node_admin_ui -.->|"administers via"| node_admin_routes
node_sharing_surfaces -.->|"likely derives card data"| node_card_routes
node_vite_entry -->|"boots"| node_vite_app

click node_server "https://github.com/sharan-2686/cardcraft/blob/main/backend/server.js"
click node_db "https://github.com/sharan-2686/cardcraft/blob/main/backend/db.js"
click node_auth_routes "https://github.com/sharan-2686/cardcraft/blob/main/backend/authRoutes.js"
click node_card_routes "https://github.com/sharan-2686/cardcraft/blob/main/backend/cardRoutes.js"
click node_admin_routes "https://github.com/sharan-2686/cardcraft/blob/main/backend/adminRoutes.js"
click node_auth_middleware "https://github.com/sharan-2686/cardcraft/blob/main/backend/authMiddleware.js"
click node_auth_controller "https://github.com/sharan-2686/cardcraft/blob/main/backend/authController.js"
click node_card_controller "https://github.com/sharan-2686/cardcraft/blob/main/backend/cardController.js"
click node_admin_controller "https://github.com/sharan-2686/cardcraft/blob/main/backend/adminController.js"
click node_email_controller "https://github.com/sharan-2686/cardcraft/blob/main/backend/emailController.js"
click node_user_model "https://github.com/sharan-2686/cardcraft/blob/main/backend/User.js"
click node_card_model "https://github.com/sharan-2686/cardcraft/blob/main/backend/Card.js"
click node_next_shell "https://github.com/sharan-2686/cardcraft/blob/main/next-app/app/layout.tsx"
click node_home "https://github.com/sharan-2686/cardcraft/blob/main/next-app/app/page.tsx"
click node_auth_context "https://github.com/sharan-2686/cardcraft/blob/main/next-app/app/context/AuthContext.tsx"
click node_account_flows "https://github.com/sharan-2686/cardcraft/blob/main/next-app/app/login/page.tsx"
click node_card_authoring "https://github.com/sharan-2686/cardcraft/blob/main/next-app/app/create-card/page.tsx"
click node_public_card "https://github.com/sharan-2686/cardcraft/blob/main/next-app/app/card/%5Bid%5D/page.tsx"
click node_admin_ui "https://github.com/sharan-2686/cardcraft/blob/main/next-app/app/admin/page.tsx"
click node_sharing_surfaces "https://github.com/sharan-2686/cardcraft/blob/main/next-app/app/qr/page.tsx"
click node_shared_ui "https://github.com/sharan-2686/cardcraft/blob/main/next-app/components/Header.tsx"
click node_vite_entry "https://github.com/sharan-2686/cardcraft/blob/main/next-app/CardConnect/CardConnect/client/src/main.jsx"
click node_vite_app "https://github.com/sharan-2686/cardcraft/blob/main/next-app/CardConnect/CardConnect/client/src/App.jsx"

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_server,node_db,node_auth_routes,node_card_routes,node_admin_routes,node_auth_middleware,node_auth_controller,node_card_controller,node_admin_controller,node_email_controller,node_user_model,node_card_model toneBlue
class node_next_shell,node_home,node_auth_context,node_account_flows,node_card_authoring,node_public_card,node_admin_ui,node_sharing_surfaces,node_shared_ui toneAmber
class node_vite_entry,node_vite_app toneMint
```

## Components

### Node backend

- [Backend server](https://github.com/sharan-2686/cardcraft/blob/main/backend/server.js): Express entry point · `backend/server.js`
- [Database initialization](https://github.com/sharan-2686/cardcraft/blob/main/backend/db.js): persistence setup · `backend/db.js`
- [Auth routes](https://github.com/sharan-2686/cardcraft/blob/main/backend/authRoutes.js): HTTP routes · `backend/authRoutes.js`
- [Card routes](https://github.com/sharan-2686/cardcraft/blob/main/backend/cardRoutes.js): HTTP routes · `backend/cardRoutes.js`
- [Admin routes](https://github.com/sharan-2686/cardcraft/blob/main/backend/adminRoutes.js): HTTP routes · `backend/adminRoutes.js`
- [Authorization middleware](https://github.com/sharan-2686/cardcraft/blob/main/backend/authMiddleware.js): auth boundary · Protects routes or controller operations. · `backend/authMiddleware.js`
- [Auth controller](https://github.com/sharan-2686/cardcraft/blob/main/backend/authController.js): application controller · `backend/authController.js`
- [Card controller](https://github.com/sharan-2686/cardcraft/blob/main/backend/cardController.js): application controller · `backend/cardController.js`
- [Admin controller](https://github.com/sharan-2686/cardcraft/blob/main/backend/adminController.js): application controller · `backend/adminController.js`
- [Email controller](https://github.com/sharan-2686/cardcraft/blob/main/backend/emailController.js): outbound delivery · Provider and delivery trigger are not established. · `backend/emailController.js`
- [User model](https://github.com/sharan-2686/cardcraft/blob/main/backend/User.js): persisted entity · `backend/User.js`
- [Card model](https://github.com/sharan-2686/cardcraft/blob/main/backend/Card.js): persisted entity · `backend/Card.js`

### Next.js app

- [App shell](https://github.com/sharan-2686/cardcraft/blob/main/next-app/app/layout.tsx): Next App Router · `next-app/app/layout.tsx`
- [Home page](https://github.com/sharan-2686/cardcraft/blob/main/next-app/app/page.tsx): route screen · `next-app/app/page.tsx`
- [Auth context](https://github.com/sharan-2686/cardcraft/blob/main/next-app/app/context/AuthContext.tsx): client identity state · `next-app/app/context/AuthContext.tsx`
- [Login and dashboard](https://github.com/sharan-2686/cardcraft/blob/main/next-app/app/login/page.tsx): route screens · `next-app/app/login/page.tsx`
- [Card authoring](https://github.com/sharan-2686/cardcraft/blob/main/next-app/app/create-card/page.tsx): route screen · `next-app/app/create-card/page.tsx`
- [Public card view](https://github.com/sharan-2686/cardcraft/blob/main/next-app/app/card/%5Bid%5D/page.tsx): dynamic route · `next-app/app/card/[id]/page.tsx`
- [Admin page](https://github.com/sharan-2686/cardcraft/blob/main/next-app/app/admin/page.tsx): route screen · `next-app/app/admin/page.tsx`
- [QR, widgets and signatures](https://github.com/sharan-2686/cardcraft/blob/main/next-app/app/qr/page.tsx): output route screens · These surfaces likely derive from card data. · `next-app/app/qr/page.tsx`
- [Shared UI chrome](https://github.com/sharan-2686/cardcraft/blob/main/next-app/components/Header.tsx): components · `next-app/components/Header.tsx`

### Parallel Vite client

Its integration with the Next.js app is not established.

- [Vite entry](https://github.com/sharan-2686/cardcraft/blob/main/next-app/CardConnect/CardConnect/client/src/main.jsx): client entry point · `next-app/CardConnect/CardConnect/client/src/main.jsx`
- [Vite app](https://github.com/sharan-2686/cardcraft/blob/main/next-app/CardConnect/CardConnect/client/src/App.jsx): client root · `next-app/CardConnect/CardConnect/client/src/App.jsx`

## Connections

- Backend server → Database initialization: initializes
- Backend server → Auth routes: mounts
- Backend server → Card routes: mounts
- Backend server → Admin routes: mounts
- Auth routes → Authorization middleware: uses
- Card routes → Authorization middleware: uses
- Admin routes → Authorization middleware: uses
- Auth routes → Auth controller: delegates to
- Card routes → Card controller: delegates to
- Admin routes → Admin controller: delegates to
- Auth controller → User model: reads and writes
- Card controller → Card model: reads and writes
- Admin controller → User model: manages
- Admin controller → Card model: manages
- Email controller → User model: uses recipient identity
- App shell → Home page: hosts
- App shell → Auth context: provides
- App shell → Shared UI chrome: composes
- Auth context → Auth routes: consumes API
- Login and dashboard → Auth routes: authenticates via
- Card authoring → Card routes: creates cards via
- Public card view → Card routes: loads card via
- Admin page → Admin routes: administers via
- QR, widgets and signatures → Card routes: likely derives card data
- Vite entry → Vite app: boots