Convert gitgram/ and aitimemachine/ from embedded git repos (which showed as opaque submodule gitlinks on GitHub) into fully-tracked first-party content. AITM now merges its 7 vendored repos as first-party engines: - memory: beads (Go task DAG) + context7 (docs SDK), unified into saved_contexts - git: vendored C git (bundled binary) + gitnexus (in-process code intelligence) - agentic: a2a (@a2a-js/sdk) + pal (AITM-managed Python subprocess) Includes the full session's product build: Gitgram web/mobile/backend features, AITM website/CLI/MCP, the unified memory layer, engine build tooling (scripts/build-engines.sh, Dockerfile, CI), docs (README, ENGINES.md, ARCHITECTURE.md), and extensive test suites. Build artifacts, node_modules, external/, and gemini-cli are gitignored. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
266 lines
7.7 KiB
Markdown
266 lines
7.7 KiB
Markdown
# 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**
|
|
```bash
|
|
git clone https://github.com/your-username/gitgram.git
|
|
cd gitgram/backend
|
|
```
|
|
|
|
2. **Install dependencies**
|
|
```bash
|
|
pnpm install
|
|
# or
|
|
npm install
|
|
```
|
|
|
|
3. **Set up environment variables**
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
Edit `.env` with your configuration (see Environment Variables section below)
|
|
|
|
4. **Set up the database**
|
|
```bash
|
|
# Generate Prisma client
|
|
pnpm prisma:generate
|
|
|
|
# Run migrations
|
|
pnpm prisma:migrate
|
|
```
|
|
|
|
5. **Start the development server**
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```javascript
|
|
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
|
|
|
|
```bash
|
|
docker build -t gitgram-backend .
|
|
docker run -p 4000:4000 --env-file .env gitgram-backend
|
|
```
|
|
|
|
### Manual Deployment
|
|
|
|
1. Build the project:
|
|
```bash
|
|
pnpm build
|
|
```
|
|
|
|
2. Run migrations:
|
|
```bash
|
|
pnpm prisma:migrate deploy
|
|
```
|
|
|
|
3. Start the server:
|
|
```bash
|
|
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
|