How trygitcord/gitcord works
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: hooks Feature hooks · feed Feed area · message Message API · code Code API
Components 22
App surfaces
Next.js route entrypoints and navigational zones.
- Root layout · Global app shell and route composition.
src/app/layout.tsx - Landing site · Public homepage and static marketing pages.
src/app/(landing) - Feed area · Private product experience with dashboard and drilldowns.
src/app/feed - Profiles · Public user profile pages by username.
src/app/user/[username]
Server API
Auth, domain routes, and request enforcement.
- Auth route · GitHub OAuth session and login callbacks.
src/app/api/auth/[...nextauth]/route.ts - User API · Profile lookup and privacy updates.
src/app/api/user - Message API · Messaging, recipient lookup, read state, and stats.
src/app/api/message - Leaderboard API · Leaderboard data endpoint.
src/app/api/leaderboard/getLeaderboard/route.ts - Code API · Create, list, delete, and redeem codes.
src/app/api/code - Feedback API · User-submitted feedback endpoint.
src/app/api/feedback/route.ts - Version API · Version lookup for the client.
src/app/api/version/getVersion/route.ts
Client layer
Providers, hooks, and shared UI composition.
- Query provider · Client query cache and request orchestration.
src/components/providers/QueryProvider.tsx - Session provider · Session state for authenticated UI.
src/components/providers/SessionProvider.tsx - Feature hooks · Domain hooks for GitHub, messages, feedback, code, and version data.
src/hooks - Shared widgets · Reusable charts, profile widgets, search, sharing, and sidebar pieces.
src/components/shared - Landing UI · Hero, features, FAQ, footer, and preview sections.
src/components/landing - UI primitives · Radix-style buttons, dialogs, inputs, charts, and other primitives.
src/components/ui
Data and integrations
Persistence, server helpers, and external platform access.
- Database layer · Mongo connection and DB-wrapped execution helpers.
src/lib/db.ts - Auth config · NextAuth setup shared by routes and middleware.
src/lib/auth.ts - Rate limiting · Server-side enforcement for sensitive endpoints.
src/lib/with-rate-limit.ts - Mongoose models · User, stats, premium, message, code, and feedback schemas.
src/models - GitHub · Contribution, repository, and profile data source.
Connections 28
- 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.