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.
gitgram-ai/gitgram/backend/ARCHITECTURE.md
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

168 lines
4.8 KiB
Markdown

# Gitgram Architecture
## System Overview
Gitgram is a social media platform for developers to showcase GitHub projects, built with:
- **Backend**: Node.js + Express + TypeScript
- **Database**: PostgreSQL with Prisma ORM
- **Mobile**: React Native with Expo
- **Real-time**: Socket.io
- **Storage**: AWS S3 (production) / Local (development)
## Architecture Diagram
```
┌─────────────┐
│ Mobile │
│ App │
│ (Expo) │
└──────┬──────┘
│
│ HTTPS/REST API
│ WebSocket
│
┌──────▼──────────────────┐
│ Load Balancer │
│ (Nginx/ALB) │
└──────┬──────────────────┘
│
├─────────────┬─────────────┐
│ │ │
┌──────▼──────┐ ┌───▼──────┐ ┌───▼──────┐
│ Backend │ │ Backend │ │ Backend │
│ Instance 1 │ │Instance 2│ │Instance 3│
└──────┬──────┘ └───┬──────┘ └───┬──────┘
│ │ │
└────────────┼─────────────┘
│
┌───────────┼───────────┐
│ │ │
┌───────▼──┐ ┌─────▼─────┐ ┌─▼──────┐
│PostgreSQL│ │ Redis │ │ S3 │
│ (Primary)│ │ (Cache) │ │(Media) │
└──────────┘ └───────────┘ └─────────┘
│
│
┌────▼──────┐
│PostgreSQL │
│ (Replica) │
└───────────┘
```
## Backend Structure
```
backend/
├── src/
│ ├── config/ # Configuration files
│ ├── controllers/ # Request handlers
│ ├── middleware/ # Express middleware
│ ├── models/ # Data models (Prisma)
│ ├── routes/ # API routes
│ ├── services/ # Business logic
│ ├── utils/ # Utilities
│ ├── validators/ # Input validation
│ └── websocket/ # Socket.io handlers
├── prisma/ # Database schema
├── tests/ # Test files
└── dist/ # Compiled JavaScript
```
## API Architecture
### RESTful API
- **Base URL**: `/api/v1`
- **Authentication**: JWT Bearer tokens
- **Response Format**: JSON
- **Error Handling**: Standardized error responses
### Endpoints
- `/api/v1/auth` - Authentication
- `/api/v1/posts` - Posts management
- `/api/v1/reels` - Reels (videos)
- `/api/v1/stories` - Stories (24h)
- `/api/v1/messages` - Direct messages
- `/api/v1/users` - User management
- `/api/v1/github` - GitHub integration
## Database Schema
### Key Models
- **User**: User accounts and profiles
- **Post**: Text, image, code posts
- **Reel**: Video content
- **Story**: Ephemeral content (24h)
- **Message**: Direct messages
- **Notification**: User notifications
- **GitHubProject**: Synced GitHub repositories
### Relationships
- User → Posts (1:N)
- User → Reels (1:N)
- User → Stories (1:N)
- User → Followers (N:M)
- Post → Comments (1:N)
- Post → Likes (N:M)
## Security
### Authentication Flow
1. User registers/logs in
2. Server generates access token (15min) + refresh token (7 days)
3. Client stores tokens securely
4. Client sends access token in Authorization header
5. On expiration, client uses refresh token to get new access token
### Authorization
- Role-based access control (user, admin, moderator)
- Resource ownership validation
- Rate limiting per endpoint
## Storage
### Media Storage
- **Development**: Local filesystem
- **Production**: AWS S3 with CDN
- **File Types**: Images, videos, code snippets
- **Max Size**: 50MB per file
## Real-time Features
### Socket.io
- Real-time messaging
- Typing indicators
- Live notifications
- Connection management
## Performance Optimizations
- Database indexes on frequently queried fields
- Response compression (gzip)
- API response caching (Redis - planned)
- Connection pooling
- Pagination for large datasets
## Monitoring
- Winston logging with daily rotation
- Request logging middleware
- Error tracking (Sentry - planned)
- Health check endpoints
## Deployment
- Docker containerization
- Kubernetes/ECS for orchestration
- CI/CD with GitHub Actions
- Automated testing on PR
- Staging and production environments