# coditor-ops/smart-link-hub architecture

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

- Interactive diagram: https://gitdiagram.com/coditor-ops/smart-link-hub
- Repository: https://github.com/coditor-ops/smart-link-hub

## Overview

#### Purpose and Entry Points
Smart Link Hub is a MERN link-in-bio platform: users authenticate, create/manage link hubs, publish public profiles, and apply conditional link visibility. The React SPA starts at `client/src/main.tsx` and route/page composition is centered in `client/src/App.tsx`. The Express API starts in `server/src/server.ts`.

#### Client Application Shell
The Vite/React TypeScript client provides both marketing, authenticated management, and public-profile experiences. Shared visual structure and responsive UI reside in `client/src/components/Layout.tsx` and global styling in `client/src/App.css`. Primary screens are `client/src/pages/Landing.tsx`, `client/src/pages/Dashboard.tsx`, `client/src/pages/HubManager.tsx`, and `client/src/pages/PublicProfile.tsx`.

#### Client State, Authentication, and API Boundary
Authentication state is owned by React context in `client/src/context/AuthContext.tsx`; theme preference is separately scoped in `client/src/context/ThemeContext.tsx`. Browser-to-server communication is centralized in `client/src/services/api.ts`, forming the principal client/API boundary. Protected management flows originate from `client/src/pages/Login.tsx`, `client/src/pages/Register.tsx`, and the dashboard/hub-management pages.

#### Hub and Link Management
A hub is the principal owned publishing unit; links belong to and are managed within hubs. The editing workflow is composed from `client/src/pages/HubManager.tsx`, `client/src/components/LinkEditor.tsx`, and `client/src/components/TargetLocationSelector.tsx`. It supports link CRUD, link imagery, and rules based on time, device, or location. QR generation is represented in `client/src/components/HubQRCode.tsx`.

#### Public Delivery and Link Resolution
Public profiles render a hub’s visible identity and eligible links through `client/src/pages/PublicProfile.tsx`, `client/src/components/ProfileHeader.tsx`, and `client/src/components/LinkCard.tsx`. Server-side resolution logic in `server/src/services/LinkResolver.ts` is the important policy boundary for deciding which links are visible under contextual rules. Link shortening/redirect-related API behavior is handled by `server/src/controllers/LinkShortenerController.ts`.

#### Server API and Domain Layer
Express routes divide the API by concern: authentication in `server/src/routes/authRoutes.ts`, hub operations in `server/src/routes/hubRoutes.ts`, link operations in `server/src/routes/linkRoutes.ts`, and asset uploads in `server/src/routes/uploadRoutes.ts`. Controllers implement request orchestration, notably `server/src/controllers/HubController.ts` and `server/src/controllers/LinkController.ts`. JWT validation is an API boundary enforced by `server/src/middleware/auth.ts`.

#### Persistence, Assets, and Runtime Infrastructure
MongoDB is accessed through Mongoose configuration in `server/src/config/database.ts`. Core persisted entities are defined by `server/src/models/User.ts`, `server/src/models/LinkHub.ts`, and `server/src/models/Link.ts`. Uploaded link/profile assets are handled by the upload route and stored under `server/uploads`. Runtime requires Node.js, MongoDB/Atlas, and environment values including `MONGO_URI`, `JWT_SECRET`, and `PORT` as indicated by `server/.env.example`.

Main entry points: [`client/src/App.tsx`](https://github.com/coditor-ops/smart-link-hub/blob/main/client/src/App.tsx) (App routes), [`server/src/routes/hubRoutes.ts`](https://github.com/coditor-ops/smart-link-hub/blob/main/server/src/routes/hubRoutes.ts) (API routes), [`client/src/services/api.ts`](https://github.com/coditor-ops/smart-link-hub/blob/main/client/src/services/api.ts) (API client), [`client/src/pages/HubManager.tsx`](https://github.com/coditor-ops/smart-link-hub/blob/main/client/src/pages/HubManager.tsx) (Hub management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React Client"]
  node_client_entry["Client entry<br/>Vite bootstrap<br/>[main.tsx]"]
  node_app_routes["App routes<br/>route composition<br/>[App.tsx]"]
  node_app_shell["Shared layout<br/>UI shell<br/>[Layout.tsx]"]
  node_auth_state["Auth state<br/>React context<br/>[AuthContext.tsx]"]
  node_theme_state["Theme state<br/>React context<br/>[ThemeContext.tsx]"]
  node_api_client["API client<br/>HTTP boundary<br/>[api.ts]"]
  node_management["Hub management<br/>editor workflow<br/>[HubManager.tsx]"]
  node_link_editor["Link editor<br/>editor component<br/>[LinkEditor.tsx]"]
  node_public_profile["Public profile<br/>public page<br/>[PublicProfile.tsx]"]
end

subgraph group_api["Express API"]
  node_server_entry["API server<br/>Express bootstrap<br/>[server.ts]"]
  node_api_routes["API routes<br/>Express routes<br/>[hubRoutes.ts]"]
  node_jwt_auth["JWT middleware<br/>API guard<br/>[auth.ts]"]
  node_hub_controller["Hub controller<br/>request controller<br/>[HubController.ts]"]
  node_link_controller["Link controller<br/>request controller<br/>[LinkController.ts]"]
  node_link_resolver["Link resolver<br/>visibility policy<br/>[LinkResolver.ts]"]
  node_shortener["Short-link redirect<br/>redirect controller"]
end

subgraph group_data["Data &amp; Assets"]
  node_mongo[("MongoDB<br/>Mongoose persistence<br/>[database.ts]")]
  node_uploads["Uploaded assets<br/>file storage"]
end

node_client_entry -->|"mounts"| node_app_routes
node_app_routes -->|"uses"| node_app_shell
node_app_routes -->|"consumes"| node_auth_state
node_app_routes -->|"consumes"| node_theme_state
node_app_routes -->|"management route"| node_management
node_app_routes -->|"public route"| node_public_profile
node_management -->|"edits links"| node_link_editor
node_management -->|"hub and link CRUD"| node_api_client
node_public_profile -->|"loads visible hub"| node_api_client
node_auth_state -->|"auth requests/token"| node_api_client
node_api_client -->|"HTTP"| node_server_entry
node_server_entry -->|"registers"| node_api_routes
node_api_routes -->|"protects management APIs"| node_jwt_auth
node_jwt_auth -->|"authorizes"| node_hub_controller
node_jwt_auth -->|"authorizes"| node_link_controller
node_api_routes -->|"redirect endpoint"| node_shortener
node_hub_controller -->|"hub persistence"| node_mongo
node_link_controller -->|"link persistence"| node_mongo
node_link_controller -->|"serves asset references"| node_uploads
node_api_routes -->|"public visibility lookup"| node_link_resolver
node_link_resolver -->|"reads hubs and links"| node_mongo
node_api_routes -->|"upload endpoints"| node_uploads

click node_client_entry "https://github.com/coditor-ops/smart-link-hub/blob/main/client/src/main.tsx"
click node_app_routes "https://github.com/coditor-ops/smart-link-hub/blob/main/client/src/App.tsx"
click node_app_shell "https://github.com/coditor-ops/smart-link-hub/blob/main/client/src/components/Layout.tsx"
click node_auth_state "https://github.com/coditor-ops/smart-link-hub/blob/main/client/src/context/AuthContext.tsx"
click node_theme_state "https://github.com/coditor-ops/smart-link-hub/blob/main/client/src/context/ThemeContext.tsx"
click node_api_client "https://github.com/coditor-ops/smart-link-hub/blob/main/client/src/services/api.ts"
click node_management "https://github.com/coditor-ops/smart-link-hub/blob/main/client/src/pages/HubManager.tsx"
click node_link_editor "https://github.com/coditor-ops/smart-link-hub/blob/main/client/src/components/LinkEditor.tsx"
click node_public_profile "https://github.com/coditor-ops/smart-link-hub/blob/main/client/src/pages/PublicProfile.tsx"
click node_server_entry "https://github.com/coditor-ops/smart-link-hub/blob/main/server/src/server.ts"
click node_api_routes "https://github.com/coditor-ops/smart-link-hub/blob/main/server/src/routes/hubRoutes.ts"
click node_jwt_auth "https://github.com/coditor-ops/smart-link-hub/blob/main/server/src/middleware/auth.ts"
click node_hub_controller "https://github.com/coditor-ops/smart-link-hub/blob/main/server/src/controllers/HubController.ts"
click node_link_controller "https://github.com/coditor-ops/smart-link-hub/blob/main/server/src/controllers/LinkController.ts"
click node_link_resolver "https://github.com/coditor-ops/smart-link-hub/blob/main/server/src/services/LinkResolver.ts"
click node_shortener "https://github.com/coditor-ops/smart-link-hub/blob/main/server/src/controllers/LinkShortenerController.ts"
click node_mongo "https://github.com/coditor-ops/smart-link-hub/blob/main/server/src/config/database.ts"
click node_uploads "https://github.com/coditor-ops/smart-link-hub/tree/main/server/uploads"

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_client_entry,node_app_routes,node_app_shell,node_auth_state,node_theme_state,node_api_client,node_management,node_link_editor,node_public_profile toneBlue
class node_server_entry,node_api_routes,node_jwt_auth,node_hub_controller,node_link_controller,node_link_resolver,node_shortener toneAmber
class node_mongo,node_uploads toneMint
```

## Components

### React Client

- [Client entry](https://github.com/coditor-ops/smart-link-hub/blob/main/client/src/main.tsx): Vite bootstrap · `client/src/main.tsx`
- [App routes](https://github.com/coditor-ops/smart-link-hub/blob/main/client/src/App.tsx): route composition · Composes marketing, management, and public-profile routes. · `client/src/App.tsx`
- [Shared layout](https://github.com/coditor-ops/smart-link-hub/blob/main/client/src/components/Layout.tsx): UI shell · `client/src/components/Layout.tsx`
- [Auth state](https://github.com/coditor-ops/smart-link-hub/blob/main/client/src/context/AuthContext.tsx): React context · `client/src/context/AuthContext.tsx`
- [Theme state](https://github.com/coditor-ops/smart-link-hub/blob/main/client/src/context/ThemeContext.tsx): React context · `client/src/context/ThemeContext.tsx`
- [API client](https://github.com/coditor-ops/smart-link-hub/blob/main/client/src/services/api.ts): HTTP boundary · Centralizes browser-to-server requests. · `client/src/services/api.ts`
- [Hub management](https://github.com/coditor-ops/smart-link-hub/blob/main/client/src/pages/HubManager.tsx): editor workflow · Creates hubs and manages links and conditional rules. · `client/src/pages/HubManager.tsx`
- [Link editor](https://github.com/coditor-ops/smart-link-hub/blob/main/client/src/components/LinkEditor.tsx): editor component · `client/src/components/LinkEditor.tsx`
- [Public profile](https://github.com/coditor-ops/smart-link-hub/blob/main/client/src/pages/PublicProfile.tsx): public page · Renders a hub's identity and eligible links. · `client/src/pages/PublicProfile.tsx`

### Express API

- [API server](https://github.com/coditor-ops/smart-link-hub/blob/main/server/src/server.ts): Express bootstrap · `server/src/server.ts`
- [API routes](https://github.com/coditor-ops/smart-link-hub/blob/main/server/src/routes/hubRoutes.ts): Express routes · Auth, hub, link, and upload endpoints. · `server/src/routes/hubRoutes.ts`
- [JWT middleware](https://github.com/coditor-ops/smart-link-hub/blob/main/server/src/middleware/auth.ts): API guard · `server/src/middleware/auth.ts`
- [Hub controller](https://github.com/coditor-ops/smart-link-hub/blob/main/server/src/controllers/HubController.ts): request controller · `server/src/controllers/HubController.ts`
- [Link controller](https://github.com/coditor-ops/smart-link-hub/blob/main/server/src/controllers/LinkController.ts): request controller · `server/src/controllers/LinkController.ts`
- [Link resolver](https://github.com/coditor-ops/smart-link-hub/blob/main/server/src/services/LinkResolver.ts): visibility policy · Applies time, device, and location eligibility rules. · `server/src/services/LinkResolver.ts`
- [Short-link redirect](https://github.com/coditor-ops/smart-link-hub/blob/main/server/src/controllers/LinkShortenerController.ts): redirect controller · `server/src/controllers/LinkShortenerController.ts`

### Data & Assets

- [MongoDB](https://github.com/coditor-ops/smart-link-hub/blob/main/server/src/config/database.ts): Mongoose persistence · Stores users, hubs, and links. · `server/src/config/database.ts`
- [Uploaded assets](https://github.com/coditor-ops/smart-link-hub/tree/main/server/uploads): file storage · Profile and link imagery. · `server/uploads`

## Connections

- Client entry → App routes: mounts
- App routes → Shared layout: uses
- App routes → Auth state: consumes
- App routes → Theme state: consumes
- App routes → Hub management: management route
- App routes → Public profile: public route
- Hub management → Link editor: edits links
- Hub management → API client: hub and link CRUD
- Public profile → API client: loads visible hub
- Auth state → API client: auth requests/token
- API client → API server: HTTP
- API server → API routes: registers
- API routes → JWT middleware: protects management APIs
- JWT middleware → Hub controller: authorizes
- JWT middleware → Link controller: authorizes
- API routes → Short-link redirect: redirect endpoint
- Hub controller → MongoDB: hub persistence
- Link controller → MongoDB: link persistence
- Link controller → Uploaded assets: serves asset references
- API routes → Link resolver: public visibility lookup
- Link resolver → MongoDB: reads hubs and links
- API routes → Uploaded assets: upload endpoints