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>
4.8 KiB
4.8 KiB
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
- User registers/logs in
- Server generates access token (15min) + refresh token (7 days)
- Client stores tokens securely
- Client sends access token in Authorization header
- 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