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>
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
- Create
app/<route>/page.tsxwith'use client'if interactive. - Wrap content in
<PageTemplate title="...">for consistent layout. - Fetch data with a service function +
useQuery. - Use CSS variables for all colors — no raw hex values.
- Add route to
middleware.tspublicPathsonly if it must be unauthenticated.
Adding a New Component
- Create
components/MyComponent.tsx. - Define a named
interface MyComponentProps. - Export as named export (not default).
- Use Tailwind + CSS variable classes for dark theme styling.