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 49b183818c Unify gitgram + aitimemachine into the monorepo (de-submodule) and merge vendored engines
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>
2026-06-23 14:14:09 +03:00

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