TypeScript 6.x makes moduleResolution=node10 (the legacy "node" resolver) a hard error (TS5107), so `tsc --noEmit` exited 2 and the backend typecheck gate was red. Add "ignoreDeprecations": "6.0" as TS itself prescribes; node10/ CommonJS resolution semantics are retained intentionally until a deliberate resolver bump. Typecheck now exits 0. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Gitgram Backend API
A social media platform API for developers where GitHub repositories become social pages. Think Instagram + Reels for GitHub projects.
Features
- Repository-as-Account Architecture: GitHub repositories can have their own social profiles
- Authentication: JWT-based auth with refresh tokens, 2FA support, OAuth (GitHub/Google)
- Posts & Feed: Create posts with code snippets, images, videos; personalized feed algorithm
- Stories & Reels: Short-form content with 24-hour expiration
- Real-time: WebSocket support for notifications, messaging, typing indicators
- GitHub Integration: Sync projects, trending repositories, recommendations
- Social Features: Follow/unfollow, likes, comments, collections, messaging
- Content Moderation: Automated NSFW detection and content filtering
- Premium Subscriptions: Polar.sh integration for premium features
Tech Stack
- Runtime: Node.js with Express 5
- Language: TypeScript
- Database: PostgreSQL with Prisma ORM
- Cache: Redis
- Real-time: Socket.io
- Storage: AWS S3
- Authentication: JWT, OAuth 2.0
- Payments: Polar.sh
- Testing: Jest + Supertest
Prerequisites
- Node.js 18+
- PostgreSQL 14+
- Redis 6+ (optional, for caching)
- pnpm (recommended) or npm
Installation
-
Clone the repository
git clone https://github.com/your-username/gitgram.git cd gitgram/backend -
Install dependencies
pnpm install # or npm install -
Set up environment variables
cp .env.example .envEdit
.envwith your configuration (see Environment Variables section below) -
Set up the database
# Generate Prisma client pnpm prisma:generate # Run migrations pnpm prisma:migrate -
Start the development server
pnpm dev
The API will be available at http://localhost:4000
Environment Variables
| Variable | Description | Required |
|---|---|---|
PORT |
Server port (default: 4000) | No |
NODE_ENV |
Environment (development/production) | No |
DATABASE_URL |
PostgreSQL connection string | Yes |
JWT_SECRET |
Secret for access tokens | Yes |
JWT_REFRESH_SECRET |
Secret for refresh tokens | Yes |
FRONTEND_URL |
Frontend URL for CORS | Yes |
GITHUB_CLIENT_ID |
GitHub OAuth client ID | Yes |
GITHUB_CLIENT_SECRET |
GitHub OAuth client secret | Yes |
GOOGLE_CLIENT_ID |
Google OAuth client ID | No |
GOOGLE_CLIENT_SECRET |
Google OAuth client secret | No |
REDIS_URL |
Redis connection URL | No |
SMTP_HOST |
SMTP server host | No |
SMTP_PORT |
SMTP server port | No |
SMTP_USER |
SMTP username | No |
SMTP_PASS |
SMTP password | No |
AWS_ACCESS_KEY_ID |
AWS access key | No |
AWS_SECRET_ACCESS_KEY |
AWS secret key | No |
AWS_REGION |
AWS region | No |
AWS_S3_BUCKET |
S3 bucket name | No |
POLAR_ACCESS_TOKEN |
Polar.sh access token | No |
POLAR_WEBHOOK_SECRET |
Polar.sh webhook secret | No |
Scripts
| Command | Description |
|---|---|
pnpm dev |
Start development server with hot reload |
pnpm build |
Build for production |
pnpm start |
Start production server |
pnpm test |
Run tests |
pnpm test:watch |
Run tests in watch mode |
pnpm test:coverage |
Run tests with coverage |
pnpm lint |
Run ESLint |
pnpm lint:fix |
Fix ESLint issues |
pnpm format |
Format code with Prettier |
pnpm prisma:generate |
Generate Prisma client |
pnpm prisma:migrate |
Run database migrations |
pnpm prisma:studio |
Open Prisma Studio |
API Documentation
Interactive API documentation is available at /api-docs when the server is running.
Main API Endpoints
Authentication
POST /api/v1/auth/register- Register new userPOST /api/v1/auth/login- LoginPOST /api/v1/auth/refresh- Refresh access tokenPOST /api/v1/auth/logout- LogoutGET /api/v1/auth/me- Get current userPOST /api/v1/auth/2fa/setup- Set up 2FAPOST /api/v1/auth/github- GitHub OAuthPOST /api/v1/auth/google- Google OAuth
Posts
GET /api/v1/posts/feed- Get personalized feedGET /api/v1/posts/explore- Get explore feedGET /api/v1/posts/trending- Get trending postsPOST /api/v1/posts- Create postGET /api/v1/posts/:id- Get postDELETE /api/v1/posts/:id- Delete postPOST /api/v1/posts/:id/like- Like postPOST /api/v1/posts/:id/comments- Add comment
GitHub Integration
GET /api/v1/github/trending/:period- Get trending reposGET /api/v1/github/search- Search repositoriesGET /api/v1/github/recommended- Get recommendationsPOST /api/v1/github/follow/:owner/:repo- Follow repositoryGET /api/v1/github/stats/:owner/:repo- Get repo stats
Stories & Reels
GET /api/v1/stories- Get stories feedPOST /api/v1/stories- Create storyGET /api/v1/reels- Get reels feedPOST /api/v1/reels- Create reel
Users
GET /api/v1/users/:username- Get user profilePUT /api/v1/users/profile- Update profilePOST /api/v1/users/:id/follow- Follow userGET /api/v1/users/:id/followers- Get followers
Project Structure
backend/
├── src/
│ ├── config/ # Configuration (swagger, etc.)
│ ├── controllers/ # Route controllers
│ ├── middleware/ # Express middleware
│ ├── routes/ # API routes
│ ├── services/ # Business logic
│ ├── utils/ # Utilities
│ ├── validators/ # Input validation
│ ├── websocket/ # Socket.io handlers
│ └── index.ts # Entry point
├── prisma/
│ └── schema.prisma # Database schema
├── tests/ # Test files
├── logs/ # Application logs
└── uploads/ # Local file uploads
Testing
# Run all tests
pnpm test
# Run tests in watch mode
pnpm test:watch
# Run tests with coverage
pnpm test:coverage
Database Schema
The database uses a Repository-as-Account architecture where:
- Account: Universal entity that can be a User, Repository, or Organization
- User: Human users with authentication
- Repository: GitHub repositories that can act as social accounts
- Post: Content created by any account type
- Story/Reel: Short-form content with expiration
See prisma/schema.prisma for the complete schema.
WebSocket Events
Connect to the WebSocket server with a JWT token:
const socket = io('http://localhost:4000', {
auth: { token: 'your-jwt-token' }
});
Events
| Event | Direction | Description |
|---|---|---|
send_message |
Client -> Server | Send a message |
receive_message |
Server -> Client | Receive a message |
typing |
Client -> Server | Typing indicator |
user_typing |
Server -> Client | User is typing |
receive_notification |
Server -> Client | New notification |
user_online |
Server -> Client | User came online |
user_offline |
Server -> Client | User went offline |
Deployment
Using Docker
docker build -t gitgram-backend .
docker run -p 4000:4000 --env-file .env gitgram-backend
Manual Deployment
-
Build the project:
pnpm build -
Run migrations:
pnpm prisma:migrate deploy -
Start the server:
pnpm start
Contributing
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
ISC