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.
caelum0x 63133da446 fix(backend): correct marathon-additions migration to incremental DDL
Replace the accidental from-empty migration (which duplicated all 16 prior
migrations and would break a fresh `migrate deploy`) with a proper incremental
migration adding only the new objects: Post.contentLanguage, the MessageReaction
and MutedWord tables, their indexes, and the MessageReaction foreign keys.

Verified the DDL against the live schema. NOTE: a fresh full `migrate deploy`
still fails on a PRE-EXISTING migration-history drift —
20260514174000_repair_scheduled_posts_schema references "ScheduledPost" which no
earlier migration creates. That predates this work; the running stack baselines
the schema (applied + migrations marked resolved) to sidestep it. Reconciling the
older migration history with schema.prisma is separate follow-up.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-29 04:07:32 +03:00
..

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

  1. Clone the repository

    git clone https://github.com/your-username/gitgram.git
    cd gitgram/backend
    
  2. Install dependencies

    pnpm install
    # or
    npm install
    
  3. Set up environment variables

    cp .env.example .env
    

    Edit .env with your configuration (see Environment Variables section below)

  4. Set up the database

    # Generate Prisma client
    pnpm prisma:generate
    
    # Run migrations
    pnpm prisma:migrate
    
  5. 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 user
  • POST /api/v1/auth/login - Login
  • POST /api/v1/auth/refresh - Refresh access token
  • POST /api/v1/auth/logout - Logout
  • GET /api/v1/auth/me - Get current user
  • POST /api/v1/auth/2fa/setup - Set up 2FA
  • POST /api/v1/auth/github - GitHub OAuth
  • POST /api/v1/auth/google - Google OAuth

Posts

  • GET /api/v1/posts/feed - Get personalized feed
  • GET /api/v1/posts/explore - Get explore feed
  • GET /api/v1/posts/trending - Get trending posts
  • POST /api/v1/posts - Create post
  • GET /api/v1/posts/:id - Get post
  • DELETE /api/v1/posts/:id - Delete post
  • POST /api/v1/posts/:id/like - Like post
  • POST /api/v1/posts/:id/comments - Add comment

GitHub Integration

  • GET /api/v1/github/trending/:period - Get trending repos
  • GET /api/v1/github/search - Search repositories
  • GET /api/v1/github/recommended - Get recommendations
  • POST /api/v1/github/follow/:owner/:repo - Follow repository
  • GET /api/v1/github/stats/:owner/:repo - Get repo stats

Stories & Reels

  • GET /api/v1/stories - Get stories feed
  • POST /api/v1/stories - Create story
  • GET /api/v1/reels - Get reels feed
  • POST /api/v1/reels - Create reel

Users

  • GET /api/v1/users/:username - Get user profile
  • PUT /api/v1/users/profile - Update profile
  • POST /api/v1/users/:id/follow - Follow user
  • GET /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

  1. Build the project:

    pnpm build
    
  2. Run migrations:

    pnpm prisma:migrate deploy
    
  3. Start the server:

    pnpm start
    

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

ISC