# roh355/short-url architecture

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

- Interactive diagram: https://gitdiagram.com/roh355/short-url
- Repository: https://github.com/roh355/short-url

## Overview

Short-URL is a web service for creating short links, redirecting visitors while recording clicks, and viewing link analytics; it also supports user registration and login. The main workflow runs from the home page’s URL form through the frontend API to the backend, which validates and stores links. Redirect requests look up a link and record a click; the stats page requests aggregates for charts and tables. Authentication is a separate frontend-to-backend flow. The README documents several server capabilities whose implementation details are only partly sampled, so those relationships are shown at the documented level.

Main entry points: [`backend/src/index.ts`](https://github.com/roh355/short-url/blob/main/backend/src/index.ts) (Express Server), [`backend/src/data-source.ts`](https://github.com/roh355/short-url/blob/main/backend/src/data-source.ts) (TypeORM Database), [`_frontend/app/components/url-form.tsx`](https://github.com/roh355/short-url/blob/main/_frontend/app/components/url-form.tsx) (URL Form), [`_frontend/app/routes/stats.tsx`](https://github.com/roh355/short-url/blob/main/_frontend/app/routes/stats.tsx) (Stats Page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_app_shell["App Shell<br/>[root.tsx]"]
  node_home_page["Home Page<br/>[home.tsx]"]
  node_url_form["URL Form<br/>[url-form.tsx]"]
  node_short_link_card["Link Cards"]
  node_recent_links["Recent Links<br/>[recents.tsx]"]
  node_api_client["API Client<br/>[axios.ts]"]
  node_stats_page["Stats Page<br/>[stats.tsx]"]
  node_stats_api["Stats API Client<br/>[stats.ts]"]
  node_analytics_views["Charts and Table<br/>[top-urls-table.tsx]"]
  node_auth_forms["Login and Register<br/>[register-form.tsx]"]
end

subgraph group_url_runtime["URL Service"]
  node_server["Express Server<br/>[index.ts]"]
  node_url_creation["Link Creation<br/>[index.ts]"]
  node_redirect_tracking["Redirect and Tracking<br/>[index.ts]"]
end

subgraph group_identity["Authentication"]
  node_auth_state["Auth Context<br/>[AuthContext.tsx]"]
  node_auth_routes["Auth Routes<br/>[auth.ts]"]
  node_auth_service["Auth Service<br/>[AuthService.ts]"]
end

subgraph group_analytics["Analytics"]
  node_url_stats["URL Statistics<br/>[index.ts]"]
  node_click_stats["Click Statistics<br/>[index.ts]"]
  node_top_links["Top Links<br/>[index.ts]"]
end

subgraph group_persistence["Persistence"]
  node_database[("TypeORM Database<br/>[data-source.ts]")]
  node_url_entity["URL Entity<br/>[URL.ts]"]
  node_click_entity["Click Entity<br/>[Click.ts]"]
  node_user_entity["User Entity<br/>[User.ts]"]
end

node_visitor(("Visitor"))

node_visitor -->|"opens"| node_home_page
node_app_shell -->|"renders routes"| node_home_page
node_home_page -->|"presents"| node_url_form
node_url_form -->|"renders result"| node_short_link_card
node_url_form -->|"submits link"| node_api_client
node_api_client -->|"POST create"| node_server
node_server -->|"routes request"| node_url_creation
node_url_creation -->|"saves link"| node_database
node_url_creation -->|"updates recents"| node_recent_links
node_visitor -->|"requests short link"| node_server
node_server -->|"routes alias"| node_redirect_tracking
node_redirect_tracking -->|"reads link and records click"| node_database
node_redirect_tracking -->|"redirects to destination"| node_visitor
node_visitor -->|"opens analytics"| node_stats_page
node_stats_page -->|"requests metrics"| node_stats_api
node_stats_api -->|"uses client"| node_api_client
node_stats_api -->|"GET stats"| node_server
node_server -->|"routes URL stats"| node_url_stats
node_server -->|"routes click stats"| node_click_stats
node_server -->|"routes top links"| node_top_links
node_url_stats -->|"queries aggregates"| node_database
node_click_stats -->|"queries aggregates"| node_database
node_top_links -->|"queries rankings"| node_database
node_stats_page -->|"renders analytics"| node_analytics_views
node_visitor -->|"enters credentials"| node_auth_forms
node_auth_forms -->|"submits credentials"| node_auth_state
node_auth_state -->|"POST auth"| node_auth_routes
node_server -->|"mounts routes"| node_auth_routes
node_auth_routes -->|"validates and delegates"| node_auth_service
node_auth_service -->|"reads and saves users"| node_database
node_database -->|"registers entity"| node_url_entity
node_database -->|"registers entity"| node_click_entity
node_database -->|"registers entity"| node_user_entity
node_url_entity -->|"relates clicks"| node_click_entity
node_user_entity -->|"relates owned links"| node_url_entity

click node_app_shell "https://github.com/roh355/short-url/blob/main/_frontend/app/root.tsx"
click node_home_page "https://github.com/roh355/short-url/blob/main/_frontend/app/routes/home.tsx"
click node_url_form "https://github.com/roh355/short-url/blob/main/_frontend/app/components/url-form.tsx"
click node_short_link_card "https://github.com/roh355/short-url/blob/main/_frontend/app/components/url-card-detailed.tsx"
click node_recent_links "https://github.com/roh355/short-url/blob/main/_frontend/app/components/recents.tsx"
click node_api_client "https://github.com/roh355/short-url/blob/main/_frontend/app/api/axios.ts"
click node_stats_page "https://github.com/roh355/short-url/blob/main/_frontend/app/routes/stats.tsx"
click node_stats_api "https://github.com/roh355/short-url/blob/main/_frontend/app/api/stats.ts"
click node_analytics_views "https://github.com/roh355/short-url/blob/main/_frontend/app/components/top-urls-table.tsx"
click node_auth_forms "https://github.com/roh355/short-url/blob/main/_frontend/app/components/register-form.tsx"
click node_auth_state "https://github.com/roh355/short-url/blob/main/_frontend/app/contexts/AuthContext.tsx"
click node_auth_routes "https://github.com/roh355/short-url/blob/main/backend/src/routes/auth.ts"
click node_auth_service "https://github.com/roh355/short-url/blob/main/backend/src/services/AuthService.ts"
click node_server "https://github.com/roh355/short-url/blob/main/backend/src/index.ts"
click node_url_creation "https://github.com/roh355/short-url/blob/main/backend/src/index.ts"
click node_redirect_tracking "https://github.com/roh355/short-url/blob/main/backend/src/index.ts"
click node_url_stats "https://github.com/roh355/short-url/blob/main/backend/src/index.ts"
click node_click_stats "https://github.com/roh355/short-url/blob/main/backend/src/index.ts"
click node_top_links "https://github.com/roh355/short-url/blob/main/backend/src/index.ts"
click node_database "https://github.com/roh355/short-url/blob/main/backend/src/data-source.ts"
click node_url_entity "https://github.com/roh355/short-url/blob/main/backend/src/entity/URL.ts"
click node_click_entity "https://github.com/roh355/short-url/blob/main/backend/src/entity/Click.ts"
click node_user_entity "https://github.com/roh355/short-url/blob/main/backend/src/entity/User.ts"

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_app_shell,node_home_page,node_url_form,node_short_link_card,node_recent_links,node_api_client,node_stats_page,node_stats_api,node_analytics_views,node_auth_forms toneBlue
class node_server,node_url_creation,node_redirect_tracking toneAmber
class node_auth_state,node_auth_routes,node_auth_service toneMint
class node_url_stats,node_click_stats,node_top_links toneRose
class node_database,node_url_entity,node_click_entity,node_user_entity,node_visitor toneIndigo
```

## Components

### Frontend

- [App Shell](https://github.com/roh355/short-url/blob/main/_frontend/app/root.tsx): `_frontend/app/root.tsx`
- [Home Page](https://github.com/roh355/short-url/blob/main/_frontend/app/routes/home.tsx): `_frontend/app/routes/home.tsx`
- [URL Form](https://github.com/roh355/short-url/blob/main/_frontend/app/components/url-form.tsx): `_frontend/app/components/url-form.tsx`
- [Link Cards](https://github.com/roh355/short-url/blob/main/_frontend/app/components/url-card-detailed.tsx): `_frontend/app/components/url-card-detailed.tsx`
- [Recent Links](https://github.com/roh355/short-url/blob/main/_frontend/app/components/recents.tsx): `_frontend/app/components/recents.tsx`
- [API Client](https://github.com/roh355/short-url/blob/main/_frontend/app/api/axios.ts): `_frontend/app/api/axios.ts`
- [Stats Page](https://github.com/roh355/short-url/blob/main/_frontend/app/routes/stats.tsx): `_frontend/app/routes/stats.tsx`
- [Stats API Client](https://github.com/roh355/short-url/blob/main/_frontend/app/api/stats.ts): `_frontend/app/api/stats.ts`
- [Charts and Table](https://github.com/roh355/short-url/blob/main/_frontend/app/components/top-urls-table.tsx): `_frontend/app/components/top-urls-table.tsx`
- [Login and Register](https://github.com/roh355/short-url/blob/main/_frontend/app/components/register-form.tsx): `_frontend/app/components/register-form.tsx`

### URL Service

- [Express Server](https://github.com/roh355/short-url/blob/main/backend/src/index.ts): `backend/src/index.ts`
- [Link Creation](https://github.com/roh355/short-url/blob/main/backend/src/index.ts): `backend/src/index.ts`
- [Redirect and Tracking](https://github.com/roh355/short-url/blob/main/backend/src/index.ts): `backend/src/index.ts`

### Authentication

- [Auth Context](https://github.com/roh355/short-url/blob/main/_frontend/app/contexts/AuthContext.tsx): `_frontend/app/contexts/AuthContext.tsx`
- [Auth Routes](https://github.com/roh355/short-url/blob/main/backend/src/routes/auth.ts): `backend/src/routes/auth.ts`
- [Auth Service](https://github.com/roh355/short-url/blob/main/backend/src/services/AuthService.ts): `backend/src/services/AuthService.ts`

### Analytics

- [URL Statistics](https://github.com/roh355/short-url/blob/main/backend/src/index.ts): `backend/src/index.ts`
- [Click Statistics](https://github.com/roh355/short-url/blob/main/backend/src/index.ts): `backend/src/index.ts`
- [Top Links](https://github.com/roh355/short-url/blob/main/backend/src/index.ts): `backend/src/index.ts`

### Persistence

- [TypeORM Database](https://github.com/roh355/short-url/blob/main/backend/src/data-source.ts): `backend/src/data-source.ts`
- [URL Entity](https://github.com/roh355/short-url/blob/main/backend/src/entity/URL.ts): `backend/src/entity/URL.ts`
- [Click Entity](https://github.com/roh355/short-url/blob/main/backend/src/entity/Click.ts): `backend/src/entity/Click.ts`
- [User Entity](https://github.com/roh355/short-url/blob/main/backend/src/entity/User.ts): `backend/src/entity/User.ts`

### Other components

- **Visitor**

## Connections

- Visitor → Home Page: opens (evidence: `README.md`)
- App Shell → Home Page: renders routes (evidence: `_frontend/app/root.tsx`)
- Home Page → URL Form: presents (evidence: `_frontend/app/routes/home.tsx`)
- URL Form → Link Cards: renders result (evidence: `_frontend/app/components/url-form.tsx`)
- URL Form → API Client: submits link (evidence: `README.md`)
- API Client → Express Server: POST create (evidence: `README.md`)
- Express Server → Link Creation: routes request (evidence: `backend/src/index.ts`)
- Link Creation → TypeORM Database: saves link (evidence: `backend/src/index.ts`)
- Link Creation → Recent Links: updates recents (evidence: `README.md`)
- Visitor → Express Server: requests short link (evidence: `README.md`)
- Express Server → Redirect and Tracking: routes alias (evidence: `backend/src/index.ts`)
- Redirect and Tracking → TypeORM Database: reads link and records click (evidence: `README.md`)
- Redirect and Tracking → Visitor: redirects to destination (evidence: `README.md`)
- Visitor → Stats Page: opens analytics (evidence: `README.md`)
- Stats Page → Stats API Client: requests metrics (evidence: `README.md`)
- Stats API Client → API Client: uses client (evidence: `_frontend/app/api/stats.ts`)
- Stats API Client → Express Server: GET stats (evidence: `README.md`)
- Express Server → URL Statistics: routes URL stats (evidence: `backend/src/index.ts`)
- Express Server → Click Statistics: routes click stats (evidence: `backend/src/index.ts`)
- Express Server → Top Links: routes top links (evidence: `backend/src/index.ts`)
- URL Statistics → TypeORM Database: queries aggregates (evidence: `README.md`)
- Click Statistics → TypeORM Database: queries aggregates (evidence: `README.md`)
- Top Links → TypeORM Database: queries rankings (evidence: `README.md`)
- Stats Page → Charts and Table: renders analytics (evidence: `README.md`)
- Visitor → Login and Register: enters credentials (evidence: `README.md`)
- Login and Register → Auth Context: submits credentials (evidence: `_frontend/app/components/register-form.tsx`)
- Auth Context → Auth Routes: POST auth (evidence: `_frontend/app/contexts/AuthContext.tsx`)
- Express Server → Auth Routes: mounts routes (evidence: `backend/src/index.ts`)
- Auth Routes → Auth Service: validates and delegates (evidence: `backend/src/routes/auth.ts`)
- Auth Service → TypeORM Database: reads and saves users (evidence: `backend/src/services/AuthService.ts`)
- TypeORM Database → URL Entity: registers entity (evidence: `backend/src/data-source.ts`)
- TypeORM Database → Click Entity: registers entity (evidence: `backend/src/data-source.ts`)
- TypeORM Database → User Entity: registers entity (evidence: `backend/src/data-source.ts`)
- URL Entity → Click Entity: relates clicks (evidence: `backend/src/entity/URL.ts`)
- User Entity → URL Entity: relates owned links (evidence: `backend/src/entity/User.ts`)
