# trygitcord/gitcord architecture

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

- Interactive diagram: https://gitdiagram.com/trygitcord/gitcord
- Repository: https://github.com/trygitcord/gitcord

## Overview

1. **Top-level shape:** Gitcord is a single Next.js 15 App Router application, not a separate frontend/backend split. The repository contains the public landing site, authenticated dashboard area, profile pages, and all server API routes in one codebase.

2. **Route boundaries:** The app is organized into three main navigational zones:
   - `src/app/(landing)` for marketing pages like home, team, contact, privacy, and terms.
   - `src/app/feed` for the authenticated product experience: dashboard, analytics, activity, inbox, leaderboard, moderator, settings, organizations, and repositories.
   - `src/app/user/[username]` for public user profile pages.

3. **Authentication and session flow:** Authentication is built around NextAuth with GitHub OAuth (`src/app/api/auth/[...nextauth]`, `src/lib/auth.ts`). The presence of `middleware.ts` suggests route protection or session-based gating for the dashboard and other private areas.

4. **Backend API layer:** The server-side API is concentrated under `src/app/api/*`. It is split by domain rather than by UI page:
   - `user` for profile lookup and privacy updates
   - `message` for inbox/notification workflows
   - `leaderboard` for ranking data
   - `code` for premium/redeem flows
   - `feedback` for user-submitted feedback
   - `version` for client/version checks  
   This API layer is the main boundary between UI and persisted data.

5. **Data storage model:** MongoDB is the primary persistence layer, with Mongoose models in `src/models` for `user`, `userStats`, `userPremium`, `message`, `code`, and `feedback`. The app’s domain data therefore centers on users, usage stats, messaging, premium access, and promotional/redeem codes.

6. **Server access helpers:** `src/lib/db.ts`, `src/lib/withDb.ts`, `src/lib/axios-server.ts`, `src/lib/axios-client.ts`, and `src/lib/axios.ts` indicate a deliberate separation between server-side database/API access and browser-side API calls. `src/lib/with-rate-limit.ts` and `src/lib/rate-limiter.ts` add a server enforcement layer for sensitive endpoints.

7. **External platform integration:** GitHub is the core external dependency. The product’s value comes from GitHub analytics, contribution data, repository stats, stars, and profile enrichment. Hooks like `useGitHubQueries`, `useGitHubStars`, and `useGithubContributions` suggest the UI pulls GitHub-derived data through query abstractions and displays it in dashboards and profile widgets.

8. **Client-side data fetching and cache:** TanStack Query is used as the client state/query layer, wired through `src/components/providers/QueryProvider.tsx`. Feature-specific hooks in `src/hooks` encapsulate requests for code, feedback, messages, version info, and GitHub data, keeping the pages/components mostly presentation-focused.

9. **Dashboard composition:** The authenticated area is assembled from reusable shared widgets in `src/components/shared`, including charts, contributor graphs, repository summaries, user activity views, search, and sharing. This is where raw stats are turned into product views like analytics, leaderboard, repository detail, and inbox experiences.

10. **UI system and presentation layer:** The repo uses a layered component structure:
    - `src/components/ui` for base primitives built on Radix UI patterns
    - `src/components/charts` for chart variants
    - `src/components/landing` for marketing sections
    - `src/components/modals` for cross-cutting interactions like feedback  
    Styling is Tailwind CSS 4 via `src/styles/globals.css`, with charts and animations handled by Recharts and Framer Motion.

11. **Content and product surfaces:** The main user journeys are:
    - anonymous visitors see the landing site,
    - authenticated users land in the feed/dashboard,
    - users explore organization/repository drilldowns,
    - profile pages expose contribution history and stats,
    - messaging and moderation provide collaboration/admin workflows.  
    This makes the app feel like a GitHub analytics workspace with social and operational features layered on top.

12. **Architecture summary for diagramming:** The cleanest diagram is a three-tier view: React/Next.js pages and components at the top, API routes plus query hooks in the middle, and MongoDB/Mongoose plus GitHub/NextAuth integrations at the bottom. The main trust boundaries are authentication, server API routes, and database access/rate-limited operations.

Main entry points: [`src/hooks`](https://github.com/trygitcord/gitcord/tree/main/src/hooks) (Feature hooks), [`src/app/feed`](https://github.com/trygitcord/gitcord/tree/main/src/app/feed) (Feed area), [`src/app/api/message`](https://github.com/trygitcord/gitcord/tree/main/src/app/api/message) (Message API), [`src/app/api/code`](https://github.com/trygitcord/gitcord/tree/main/src/app/api/code) (Code API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App surfaces"]
  node_root_layout["Root layout<br/>Next.js shell<br/>[layout.tsx]"]
  node_landing_site["Landing site<br/>Marketing routes"]
  node_feed_area["Feed area<br/>Authenticated routes"]
  node_profile_pages["Profiles<br/>Public profile routes"]
end

subgraph group_api["Server API"]
  node_auth_route["Auth route<br/>NextAuth endpoint<br/>[route.ts]"]
  node_user_api["User API<br/>Profile domain"]
  node_message_api["Message API<br/>Inbox domain"]
  node_leaderboard_api["Leaderboard API<br/>Ranking domain<br/>[route.ts]"]
  node_code_api["Code API<br/>Premium codes"]
  node_feedback_api["Feedback API<br/>Feedback domain<br/>[route.ts]"]
  node_version_api["Version API<br/>Client check<br/>[route.ts]"]
end

subgraph group_client["Client layer"]
  node_query_provider["Query provider<br/>TanStack Query<br/>[QueryProvider.tsx]"]
  node_session_provider["Session provider<br/>Auth context"]
  node_hooks["Feature hooks<br/>Client data hooks"]
  node_shared_ui["Shared widgets<br/>Dashboard components"]
  node_landing_ui["Landing UI<br/>Marketing components"]
  node_ui_primitives["UI primitives<br/>Base components"]
end

subgraph group_data["Data and integrations"]
  node_db_layer[("Database layer<br/>Mongo helpers<br/>[db.ts]")]
  node_auth_lib["Auth config<br/>[auth.ts]"]
  node_rate_limit["Rate limiting<br/>Server guard<br/>[with-rate-limit.ts]"]
  node_models[("Mongoose models<br/>Persistence models")]
  node_github_ext(("GitHub<br/>External platform"))
end

node_root_layout -->|"renders"| node_landing_site
node_root_layout -->|"renders"| node_feed_area
node_root_layout -->|"renders"| node_profile_pages
node_feed_area -->|"composes"| node_shared_ui
node_landing_site -->|"composes"| node_landing_ui
node_feed_area -->|"uses"| node_query_provider
node_feed_area -->|"uses"| node_session_provider
node_shared_ui -->|"built on"| node_ui_primitives
node_landing_ui -->|"built on"| node_ui_primitives
node_hooks -->|"connects"| node_query_provider
node_hooks -->|"fetches"| node_github_ext
node_hooks -->|"calls"| node_message_api
node_hooks -->|"calls"| node_code_api
node_hooks -->|"calls"| node_feedback_api
node_hooks -->|"calls"| node_version_api
node_auth_route -->|"configured by"| node_auth_lib
node_feed_area -.->|"protected by"| node_auth_route
node_user_api -->|"reads/writes"| node_db_layer
node_message_api -->|"reads/writes"| node_db_layer
node_code_api -->|"reads/writes"| node_db_layer
node_feedback_api -->|"writes"| node_db_layer
node_user_api -->|"uses"| node_models
node_message_api -->|"uses"| node_models
node_code_api -->|"uses"| node_models
node_feedback_api -->|"uses"| node_models
node_user_api -.->|"protected by"| node_rate_limit
node_message_api -.->|"protected by"| node_rate_limit
node_code_api -.->|"protected by"| node_rate_limit

click node_root_layout "https://github.com/trygitcord/gitcord/blob/main/src/app/layout.tsx"
click node_landing_site "https://github.com/trygitcord/gitcord/tree/main/src/app/(landing)"
click node_feed_area "https://github.com/trygitcord/gitcord/tree/main/src/app/feed"
click node_profile_pages "https://github.com/trygitcord/gitcord/tree/main/src/app/user/[username]"
click node_auth_route "https://github.com/trygitcord/gitcord/blob/main/src/app/api/auth/[...nextauth]/route.ts"
click node_user_api "https://github.com/trygitcord/gitcord/tree/main/src/app/api/user"
click node_message_api "https://github.com/trygitcord/gitcord/tree/main/src/app/api/message"
click node_leaderboard_api "https://github.com/trygitcord/gitcord/blob/main/src/app/api/leaderboard/getLeaderboard/route.ts"
click node_code_api "https://github.com/trygitcord/gitcord/tree/main/src/app/api/code"
click node_feedback_api "https://github.com/trygitcord/gitcord/blob/main/src/app/api/feedback/route.ts"
click node_version_api "https://github.com/trygitcord/gitcord/blob/main/src/app/api/version/getVersion/route.ts"
click node_query_provider "https://github.com/trygitcord/gitcord/blob/main/src/components/providers/QueryProvider.tsx"
click node_session_provider "https://github.com/trygitcord/gitcord/blob/main/src/components/providers/SessionProvider.tsx"
click node_hooks "https://github.com/trygitcord/gitcord/tree/main/src/hooks"
click node_shared_ui "https://github.com/trygitcord/gitcord/tree/main/src/components/shared"
click node_landing_ui "https://github.com/trygitcord/gitcord/tree/main/src/components/landing"
click node_ui_primitives "https://github.com/trygitcord/gitcord/tree/main/src/components/ui"
click node_db_layer "https://github.com/trygitcord/gitcord/blob/main/src/lib/db.ts"
click node_auth_lib "https://github.com/trygitcord/gitcord/blob/main/src/lib/auth.ts"
click node_rate_limit "https://github.com/trygitcord/gitcord/blob/main/src/lib/with-rate-limit.ts"
click node_models "https://github.com/trygitcord/gitcord/tree/main/src/models"

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_root_layout,node_landing_site,node_feed_area,node_profile_pages toneBlue
class node_auth_route,node_user_api,node_message_api,node_leaderboard_api,node_code_api,node_feedback_api,node_version_api toneAmber
class node_query_provider,node_session_provider,node_hooks,node_shared_ui,node_landing_ui,node_ui_primitives toneMint
class node_db_layer,node_auth_lib,node_rate_limit,node_models,node_github_ext toneRose
```

## Components

### App surfaces

Next.js route entrypoints and navigational zones.

- [Root layout](https://github.com/trygitcord/gitcord/blob/main/src/app/layout.tsx): Next.js shell · Global app shell and route composition. · `src/app/layout.tsx`
- [Landing site](https://github.com/trygitcord/gitcord/tree/main/src/app/(landing)): Marketing routes · Public homepage and static marketing pages. · `src/app/(landing)`
- [Feed area](https://github.com/trygitcord/gitcord/tree/main/src/app/feed): Authenticated routes · Private product experience with dashboard and drilldowns. · `src/app/feed`
- [Profiles](https://github.com/trygitcord/gitcord/tree/main/src/app/user/[username]): Public profile routes · Public user profile pages by username. · `src/app/user/[username]`

### Server API

Auth, domain routes, and request enforcement.

- [Auth route](https://github.com/trygitcord/gitcord/blob/main/src/app/api/auth/[...nextauth]/route.ts): NextAuth endpoint · GitHub OAuth session and login callbacks. · `src/app/api/auth/[...nextauth]/route.ts`
- [User API](https://github.com/trygitcord/gitcord/tree/main/src/app/api/user): Profile domain · Profile lookup and privacy updates. · `src/app/api/user`
- [Message API](https://github.com/trygitcord/gitcord/tree/main/src/app/api/message): Inbox domain · Messaging, recipient lookup, read state, and stats. · `src/app/api/message`
- [Leaderboard API](https://github.com/trygitcord/gitcord/blob/main/src/app/api/leaderboard/getLeaderboard/route.ts): Ranking domain · Leaderboard data endpoint. · `src/app/api/leaderboard/getLeaderboard/route.ts`
- [Code API](https://github.com/trygitcord/gitcord/tree/main/src/app/api/code): Premium codes · Create, list, delete, and redeem codes. · `src/app/api/code`
- [Feedback API](https://github.com/trygitcord/gitcord/blob/main/src/app/api/feedback/route.ts): Feedback domain · User-submitted feedback endpoint. · `src/app/api/feedback/route.ts`
- [Version API](https://github.com/trygitcord/gitcord/blob/main/src/app/api/version/getVersion/route.ts): Client check · Version lookup for the client. · `src/app/api/version/getVersion/route.ts`

### Client layer

Providers, hooks, and shared UI composition.

- [Query provider](https://github.com/trygitcord/gitcord/blob/main/src/components/providers/QueryProvider.tsx): TanStack Query · Client query cache and request orchestration. · `src/components/providers/QueryProvider.tsx`
- [Session provider](https://github.com/trygitcord/gitcord/blob/main/src/components/providers/SessionProvider.tsx): Auth context · Session state for authenticated UI. · `src/components/providers/SessionProvider.tsx`
- [Feature hooks](https://github.com/trygitcord/gitcord/tree/main/src/hooks): Client data hooks · Domain hooks for GitHub, messages, feedback, code, and version data. · `src/hooks`
- [Shared widgets](https://github.com/trygitcord/gitcord/tree/main/src/components/shared): Dashboard components · Reusable charts, profile widgets, search, sharing, and sidebar pieces. · `src/components/shared`
- [Landing UI](https://github.com/trygitcord/gitcord/tree/main/src/components/landing): Marketing components · Hero, features, FAQ, footer, and preview sections. · `src/components/landing`
- [UI primitives](https://github.com/trygitcord/gitcord/tree/main/src/components/ui): Base components · Radix-style buttons, dialogs, inputs, charts, and other primitives. · `src/components/ui`

### Data and integrations

Persistence, server helpers, and external platform access.

- [Database layer](https://github.com/trygitcord/gitcord/blob/main/src/lib/db.ts): Mongo helpers · Mongo connection and DB-wrapped execution helpers. · `src/lib/db.ts`
- [Auth config](https://github.com/trygitcord/gitcord/blob/main/src/lib/auth.ts): NextAuth config · NextAuth setup shared by routes and middleware. · `src/lib/auth.ts`
- [Rate limiting](https://github.com/trygitcord/gitcord/blob/main/src/lib/with-rate-limit.ts): Server guard · Server-side enforcement for sensitive endpoints. · `src/lib/with-rate-limit.ts`
- [Mongoose models](https://github.com/trygitcord/gitcord/tree/main/src/models): Persistence models · User, stats, premium, message, code, and feedback schemas. · `src/models`
- **GitHub**: External platform · Contribution, repository, and profile data source.

## Connections

- Root layout → Landing site: renders · Global shell includes marketing routes.
- Root layout → Feed area: renders · Global shell includes authenticated product routes.
- Root layout → Profiles: renders · Global shell includes public profiles.
- Feed area → Shared widgets: composes · Dashboard screens are built from shared widgets.
- Landing site → Landing UI: composes · Marketing pages use landing-specific sections.
- Feed area → Query provider: uses · Authenticated UI relies on client query caching.
- Feed area → Session provider: uses · Private routes consume session state.
- Shared widgets → UI primitives: built on · Shared widgets depend on the base UI system.
- Landing UI → UI primitives: built on · Landing sections use the same primitives.
- Feature hooks → Query provider: connects · Hooks operate through the query cache layer.
- Feature hooks → GitHub: fetches · GitHub-derived analytics and profile data.
- Feature hooks → Message API: calls · Inbox and messaging requests.
- Feature hooks → Code API: calls · Redeem and premium code workflows.
- Feature hooks → Feedback API: calls · Feedback submission flows.
- Feature hooks → Version API: calls · Client version checks.
- Auth route → Auth config: configured by · NextAuth route uses shared auth config.
- Feed area → Auth route: protected by · Authenticated area depends on auth/session gating.
- User API → Database layer: reads/writes · Profile and privacy endpoints touch persistence.
- Message API → Database layer: reads/writes · Message workflows are database-backed.
- Code API → Database layer: reads/writes · Code creation and redemption are stored server-side.
- Feedback API → Database layer: writes · Feedback is persisted.
- User API → Mongoose models: uses · Profile endpoints use user-related schemas.
- Message API → Mongoose models: uses · Inbox endpoints use message and user schemas.
- Code API → Mongoose models: uses · Premium code endpoints use code schemas.
- Feedback API → Mongoose models: uses · Feedback endpoint uses feedback schema.
- User API → Rate limiting: protected by · Sensitive endpoints are rate-limited where needed.
- Message API → Rate limiting: protected by · Message operations are rate-limited.
- Code API → Rate limiting: protected by · Code redemption and admin actions are guarded.
