This repository has been archived on 2026-11-17. You can view files and clone it, but cannot push or open issues or pull requests.
gitgram-ai/gitgram/web/CLAUDE.md
caelum0x 64fbe9f474 feat: round-3 deep product build-out (69 gaps closed, all 7 products green)
Deep-audit + build-out across all products to fully-usable state; all typecheck clean.

- gitgram-web (99): wire Store feature to real endpoints, close 9 gaps
- gitgram-backend (100): close 8 flow gaps, document infra-provisioning items
- gitgram-mobile (90): fix API base-URL/path mismatch (404s) + copy proximity
  components into components/proximity wired to real screens; 15 gaps, +react-native-svg
- aitm-core (95): wire natural-language CLI flow end-to-end; 11 gaps
- aitm-api (97): fix teams metadata runtime bug; copy a2a-js server/client/grpc
  into src/a2a and wire A2A route; crates.io package search; 8 gaps
- aitm-mcp (100): fix A2A client/server card mismatch; 9 gaps
- aitm-website (95): build missing docs routes; 9 gaps

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-28 13:54:57 +03:00

8.6 KiB

Gitgram Web — CLAUDE.md

AITM Protocol (Required)

Before any file change: before_action({ action: "description" }) After changes: after_action({ action: "what was done", success: true })


Tech Stack

  • Framework: Next.js 14 App Router (app/ directory)
  • Language: TypeScript
  • Styling: Tailwind CSS + CSS custom properties (dark theme)
  • Font: Space Grotesk (next/font/google)
  • State: Zustand (store/authStore.ts) + TanStack React Query (@tanstack/react-query)
  • HTTP: Axios (services/api.ts) — withCredentials: true, auto-refreshes httpOnly cookies
  • Testing: Vitest + @testing-library/react + axios-mock-adapter (72/72 pass)
  • E2E: Playwright (playwright.config.ts)
  • Error tracking: Sentry (sentry.*.config.ts)

Dark Theme Colors (CSS Custom Properties in app/globals.css)

Variable Hex Usage
--background #0A0C10 Page background
--background-light #161b22 Section backgrounds
--surface #161b22 Card backgrounds
--surface-secondary #21262d Hover states
--border #30363d Borders
--foreground #c9d1d9 Primary text
--foreground-secondary #8b949e Secondary text
--primary #58a6ff GitHub blue, links
--accent #238636 GitHub green, CTAs
--error #da3633 Error states
--warning #d29922 Warning states

Always use CSS variables (bg-[var(--surface)]) not raw hex values.


App Router Structure (app/)

Route Purpose
page.tsx Landing / home feed
(auth)/ Auth group — login/register/forgot-password
[username]/ User profile page
[owner]/[repo]/ Repository detail page
feed/ Authenticated social feed
explore/ Discover repos and developers
messages/ Direct messages
notifications/ Notification center
settings/ User account settings
search/ Search results
post/[id]/ Single post detail
trending/ Trending repos and hashtags
discover/ Curated discovery
create/ Create a new post
analytics/ Profile/repo analytics
store/ Creator store
pricing/ Subscription pricing
admin/ Admin panel
api/ Next.js API routes (proxies / callbacks)

ConditionalLayout.tsx wraps app/ — hides sidebar on auth/landing pages.


Components (components/)

Component Description
Navbar.tsx Top navigation bar with user menu
Navigation.tsx Left sidebar navigation links
Feed.tsx Paginated post feed with infinite scroll
PostCard.tsx Single post card with like/comment/share
CreatePost.tsx Post composer (text, image, code)
CreatePostWithRepo.tsx Post composer pre-linked to a repository
RepoCard.tsx Repository summary card
RepositorySocialCard.tsx Repo card with social stats
UserProfile.tsx Full user profile header
UserList.tsx List of user avatars with follow buttons
GitHubActivityFeed.tsx Live GitHub events feed
GitHubProfileCard.tsx GitHub stats summary card
StoriesRing.tsx Instagram-style stories ring
StoryViewer.tsx Fullscreen story viewer
StoryReactions.tsx Emoji reaction bar for stories
AitmChangeStoryCard.tsx AITM checkpoint as a story card
CommentThread.tsx Nested comment thread
RealTimeComments.tsx WebSocket-backed live comments
SearchBar.tsx Global search input
UserSearch.tsx User-specific search dropdown
TrendingHashtags.tsx Hashtag trending list
TrendingRepos.tsx Repository trending list
NotificationBell.tsx Bell icon with unread badge
NotificationBadge.tsx Numeric unread count badge
CodeBlock.tsx Syntax-highlighted code display
CodeSnippetCard.tsx Shareable code snippet card
CodeSnippetEmbed.tsx Embeddable snippet widget
ImageCarousel.tsx Multi-image swipe carousel
VideoPlayer.tsx Video player for reels/stories
VirtualList.tsx Virtualised list for performance
PageTemplate.tsx Consistent page wrapper with title
EmptyState.tsx Zero-state placeholder illustration
LoadingSpinner.tsx Centered loading indicator
SkeletonLoader.tsx Content skeleton during fetch
ErrorBoundary.tsx React error boundary wrapper
OfflineIndicator.tsx Banner when network is offline
OnlineIndicator.tsx User presence dot
AdCard.tsx Sponsored ad card
AdPost.tsx Ad rendered in-feed
AnalyticsChart.tsx Recharts-based analytics chart
BookmarkButton.tsx Save/unsave post button
EmojiPicker.tsx Emoji selection popover
GifPicker.tsx GIF selection popover
MentionInput.tsx Text input with @mention autocomplete
TypingIndicator.tsx "User is typing…" indicator
PullToRefresh.tsx Mobile pull-to-refresh gesture
RichContent.tsx Renders markdown + embeds
ShareCheckpointButton.tsx Share AITM checkpoint action
RepoToTextWidget.tsx Convert repo to readable text
ThemeSelector.tsx Theme switcher UI
VerifiedBadge.tsx Blue checkmark for verified users
AccountSwitcher.tsx Multi-account switcher
PostGrid.tsx Instagram-style photo grid
LandingNavbar.tsx Navbar for unauthenticated landing pages
Accessibility.tsx Skip-to-content and ARIA helpers
composer/ Subcomponents for the post composer
repo/ Subcomponents for repository views
ui/ Primitive UI components (button, toast, modal, …)

API Integration (services/)

Base URL: NEXT_PUBLIC_API_URL (default: http://localhost:4000/api) Versioning: paths auto-prefixed with /v1 via normalizeApiPath() Auth: httpOnly cookies sent automatically (withCredentials: true); token refresh on 401 is handled transparently in the Axios interceptor.

Service Responsibility
api.ts Axios instance, interceptors, token refresh
authService.ts Login, register, logout, 2FA, OAuth
userService.ts Profile CRUD, follow/unfollow
postService.ts Create/read/delete posts, likes, paginated feed (getFeed)
repoService.ts Repository data, claim
messageService.ts DMs and conversations
notificationService.ts Notification list and mark-read
githubService.ts GitHub OAuth + activity
storyService.ts Stories CRUD
reelService.ts Reels CRUD
analyticsService.ts Analytics data
trendingService.ts Trending repos/hashtags
snippetService.ts Code snippets
aitmService.ts AITM checkpoint integration
subscriptionService.ts Polar.sh subscription management
storeService.ts Creator store items
settingsService.ts User settings
adService.ts / adCampaignService.ts Ads
momentService.ts Moments feed
draftService.ts Draft posts
locationService.ts Location tagging
feedbackService.ts User feedback submission
verificationPurchaseService.ts Verified badge purchase

State Management

Zustand — store/authStore.ts

import { useAuthStore } from '@/store/authStore'
// or via alias:
import { useAuth } from '@/hooks/useAuth'

const { user, isAuthenticated, login, logout } = useAuthStore()

Fields: user, isAuthenticated, isInitialized, pending2FA, tempToken. initialize() is called once in app/providers.tsx on mount (reads session from httpOnly cookie).

TanStack React Query

QueryClient created in app/providers.tsx. Use useQuery / useMutation for server data. Pair with service functions: useQuery({ queryKey: ['posts'], queryFn: postService.getFeed }).


Auth Guard

Auth is enforced in middleware.ts. Routes not in publicPaths redirect to /login when unauthenticated. Public paths include: /, /login, /register, /forgot-password, /reset-password, /pricing, /terms, /privacy-policy, /auth/github/callback, /auth/google/callback.

To make a new route public, add it to the publicPaths array in middleware.ts.


Adding a New Page

  1. Create app/<route>/page.tsx with 'use client' if interactive.
  2. Wrap content in <PageTemplate title="..."> for consistent layout.
  3. Fetch data with a service function + useQuery.
  4. Use CSS variables for all colors — no raw hex values.
  5. Add route to middleware.ts publicPaths only if it must be unauthenticated.

Adding a New Component

  1. Create components/MyComponent.tsx.
  2. Define a named interface MyComponentProps.
  3. Export as named export (not default).
  4. Use Tailwind + CSS variable classes for dark theme styling.