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/README.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

629 lines
12 KiB
Markdown

# 🚀 Gitgram
**Instagram-like social platform for developers** - Share projects, connect through code, and build your developer network.
[![Status](https://img.shields.io/badge/status-production--ready-brightgreen)]()
[![Progress](https://img.shields.io/badge/progress-100%25-blue)]()
[![Phases](https://img.shields.io/badge/phases-7/7%20complete-success)]()
[![License](https://img.shields.io/badge/license-ISC-green)]()
**🎉 ALL 7 PHASES COMPLETE - READY TO LAUNCH! 🎉**
---
## ✨ Features
### 🔐 Authentication
- Email/Password registration & login
- OAuth (GitHub & Google)
- JWT authentication with refresh tokens
- Email verification & password reset
### 📱 Social Features
- User profiles with avatars
- Follow/Unfollow system
- Posts (photos, videos, multi-photo)
- Stories (24h expiry) with reactions & replies
- Reels (vertical video)
- Comments & Likes
- Real-time messaging
- Notifications
### 🎯 Discovery
- Explore page
- Hashtag pages & trending
- Search (users, posts, hashtags)
- Suggested users
- Collections (organize saved posts)
### 💻 GitHub Integration
- OAuth login
- Project sync
- Repository links
- Developer profiles
- Account claiming
### 🎨 UI/UX
- Dark mode
- Responsive design
- Infinite scroll
- Image carousel
- Video player
- Emoji picker
- Skeleton loaders
- Error boundaries
- Empty states
### 📱 Mobile App
- 150+ screens
- Camera integration
- Push notifications
- Offline support
- Biometric auth
- Most core feature flows implemented; some mobile-only account flows are still placeholders (see `gitgram/mobile/app/**` TODO markers).
### 💰 Monetization
- Subscription plans (Free, Premium, Creator)
- Polar.sh payment integration
- Advanced analytics dashboard
- Content scheduling
- Advertising platform
- Creator tools
---
## 🏗️ Architecture
### Backend
- **Runtime**: Node.js + Express
- **Database**: PostgreSQL + Prisma ORM
- **Real-time**: Socket.io
- **Storage**: AWS S3 / Cloudinary
- **Email**: Resend
- **Caching**: Redis
- **Monitoring**: Sentry
### Frontend Web
- **Framework**: Next.js 14 (App Router)
- **Styling**: Tailwind CSS
- **State**: Zustand
- **Real-time**: Socket.io Client
### Mobile
- **Framework**: React Native + Expo
- **Navigation**: React Navigation
- **State**: Zustand
---
## 🚀 Quick Start
### Prerequisites
- Node.js >= 18.0.0
- PostgreSQL
- Redis (optional)
### Installation
```bash
# Install all dependencies
npm run install:all
# Set up environment variables
cp backend/.env.example backend/.env
cp web/.env.example web/.env.local
# Run database migrations
cd backend
npx prisma migrate dev
cd ..
# Start development servers
npm run dev
```
### Development URLs
- Frontend (Next.js): http://localhost:3000
- Backend (Express API): http://localhost:4000
- API Docs (dev only): http://localhost:4000/api-docs
Notes:
- The backend port is controlled by `PORT`. In the monorepo `docker-compose.yml` it's set to `4000`.
- The frontend port is controlled by Next.js (`3000` by default).
---
## 📦 Project Structure
```
gitgram/
├── backend/ # Node.js + Express + Prisma
│ ├── src/
│ │ ├── controllers/ # 15+ controllers
│ │ ├── routes/ # 100+ endpoints
│ │ ├── middleware/ # Auth, rate limiting, caching
│ │ ├── services/ # Redis, Sentry, storage
│ │ └── websocket/ # Socket.io real-time
│ └── prisma/
│ └── schema.prisma # 22 database models
├── web/ # Next.js 14 web app
│ ├── app/ # 35+ pages
│ ├── components/ # 55+ components
│ ├── services/ # API clients
│ └── hooks/ # Custom hooks
├── mobile/ # React Native + Expo
│ ├── app/ # 150+ screens
│ └── services/ # 27 API services
└── scripts/ # Deployment & utility scripts
```
---
## 📊 Statistics
- **Features**: 85+ completed
- **Backend**: 110+ API endpoints, 27 models
- **Frontend**: 40+ pages, 60+ components
- **Mobile**: 150+ screens, 27 services
- **Code**: 30,000+ lines
- **Progress**: 100% complete
---
## 🛠️ Available Scripts
### Root Level
```bash
npm run install:all # Install all dependencies
npm run dev # Start backend + web
npm run dev:all # Start all (backend + web + mobile)
npm run build # Build backend + web
npm run test # Run all tests
npm run lint # Lint all projects
```
### Backend
```bash
cd backend
npm run dev # Start dev server
npm run build # Build for production
npm start # Start production server
npm run prisma:migrate # Run database migrations
npm run prisma:studio # Open Prisma Studio
```
### Frontend
```bash
cd web
npm run dev # Start dev server
npm run build # Build for production
npm start # Start production server
npm run test # Run Vitest suite
npm run test:e2e # Run Playwright suite
npm run test:e2e:repo-text # Run focused repo routing/text browser gate
```
### Mobile
```bash
cd mobile
npm start # Start Expo
npm run android # Run on Android
npm run ios # Run on iOS
```
---
## 🚀 Deployment
### Quick Deploy
```bash
./scripts/deploy.sh
```
### Manual Deploy
**Backend (Railway)**
```bash
cd backend
npm install
npx prisma generate
npx prisma migrate deploy
npm run build
npm start
```
**Frontend (Vercel)**
```bash
cd web
npm install
npm run build
vercel --prod
```
See [DEPLOYMENT_GUIDE.md](./DEPLOYMENT_GUIDE.md) for detailed instructions.
---
## 📝 Documentation
- [Deployment Guide](./DEPLOYMENT_GUIDE.md) - Complete deployment walkthrough
- [Next Actions](./NEXT_ACTIONS.md) - Step-by-step action plan
- [MVP Launch Checklist](./MVP_LAUNCH_CHECKLIST.md) - 4-week launch plan
- [Implementation Roadmap](./IMPLEMENTATION_ROADMAP.md) - Feature roadmap
- [Final Status](./FINAL_STATUS.md) - Comprehensive status report
---
## 🧪 Testing
```bash
# Run all tests
npm test
# Backend tests
cd backend && npm test
# Frontend tests
cd web && npm test
# Mobile tests
cd mobile && npm test
```
---
## 🔒 Security
- JWT authentication with refresh tokens
- Rate limiting (5/min auth, 100/min API)
- CORS protection
- Security headers (Helmet)
- Input validation
- SQL injection prevention
- XSS prevention
- CSRF protection
---
## 💰 Cost Estimate
### Free Tier
- Supabase: $0 (500MB database)
- Vercel: $0 (100GB bandwidth)
- Upstash: $0 (10K commands/day)
- Sentry: $0 (5K errors/month)
- Resend: $0 (3K emails/month)
- Railway: $5 (backend hosting)
**Total**: $5/month
---
## 🤝 Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
---
## 📄 License
ISC License - see [LICENSE](./LICENSE) file for details
---
## 🙏 Acknowledgments
- Next.js team for the amazing framework
- Prisma team for the excellent ORM
- Expo team for React Native tooling
- All open source contributors
---
## 📞 Support
- Documentation: [/docs](./docs)
- Issues: [GitHub Issues](https://github.com/yourusername/gitgram/issues)
- Email: support@gitgram.app
---
## 🎯 Roadmap
- [x] Core social features
- [x] Real-time messaging
- [x] GitHub integration
- [x] Mobile app
- [x] Dark mode
- [x] Monetization (subscriptions, ads)
- [ ] Two-factor authentication
- [ ] Content moderation AI
- [ ] Advanced AI features
---
**Built with ❤️ by developers, for developers**
---
*Last Updated: November 30, 2025*
```
gitgram/
├── backend/ # Node.js + Express + Prisma backend
├── mobile/ # React Native + Expo mobile app
├── web/ # Next.js web application
├── scripts/ # Utility scripts for project management
└── package.json # Root package.json with centralized scripts
```
## 🚀 Quick Start
### Prerequisites
- Node.js >= 18.0.0
- npm >= 9.0.0
- PostgreSQL (for backend)
- Expo CLI (for mobile development)
### Installation
Install all dependencies for all projects:
```bash
npm run install:all
```
Or use the installation script:
```bash
chmod +x scripts/install-all.sh
./scripts/install-all.sh
```
### Development
Start development servers:
```bash
npm run dev # Backend + Web (recommended)
npm run dev:all # Backend + Web + Mobile (all projects)
```
Or use the scripts:
```bash
./scripts/dev.sh # Backend + Web
./scripts/dev-all.sh # All projects
```
Or start specific projects:
```bash
npm run dev:backend # Backend only (port 3000)
npm run dev:web # Web only (port 3001)
npm run dev:mobile # Mobile (Expo)
```
### Production Build
Build all projects:
```bash
npm run build # Backend + Web
npm run build:all # Backend + Web + Mobile
```
Build specific projects:
```bash
npm run build:backend
npm run build:web
npm run build:mobile
```
### Production Start
Start production servers:
```bash
npm start # Backend + Web (production mode)
```
Or use the script:
```bash
./scripts/start.sh # Backend + Web (auto-builds if needed)
```
**Note:** Make sure to build projects first with `npm run build` before starting production servers.
## 📦 Package Management
### Add a package
Add a package to a specific project:
```bash
npm run add:backend <package-name>
npm run add:mobile <package-name>
npm run add:web <package-name>
```
Or use the script:
```bash
./scripts/add-package.sh backend express
./scripts/add-package.sh mobile react-native-vector-icons
./scripts/add-package.sh web next-auth
```
Add a dev dependency:
```bash
./scripts/add-package.sh backend jest --dev
```
### Remove a package
```bash
npm run remove:backend <package-name>
npm run remove:mobile <package-name>
npm run remove:web <package-name>
```
Or use the script:
```bash
./scripts/remove-package.sh backend express
```
## 🧹 Cleanup
Clean all build artifacts and node_modules:
```bash
npm run clean:all
```
Or use the script:
```bash
./scripts/clean-all.sh
```
## 🧪 Testing
Run all tests:
```bash
npm test
```
Run tests for specific projects:
```bash
npm run test:backend
npm run test:mobile
```
Watch mode:
```bash
npm run test:watch
```
## 🔍 Linting
Lint all projects:
```bash
npm run lint
```
Fix linting issues:
```bash
npm run lint:fix
```
## 🗄️ Database
Generate Prisma client:
```bash
npm run prisma:generate
```
Run migrations:
```bash
npm run prisma:migrate
```
Open Prisma Studio:
```bash
npm run prisma:studio
```
## 📝 Available Scripts
### Installation
- `install:all` - Install dependencies for all projects
- `install:backend` - Install backend dependencies
- `install:mobile` - Install mobile dependencies
- `install:web` - Install web dependencies
### Development
- `dev` - Start backend and web (parallel)
- `dev:all` - Start all projects (parallel)
- `dev:backend` - Start backend only
- `dev:mobile` - Start mobile only
- `dev:web` - Start web only
### Build
- `build` - Build backend and web
- `build:backend` - Build backend
- `build:web` - Build web
- `build:mobile` - Build mobile
### Testing
- `test` - Run all tests
- `test:backend` - Test backend
- `test:mobile` - Test mobile
- `test:watch` - Watch mode for all tests
### Linting
- `lint` - Lint all projects
- `lint:fix` - Fix linting issues in all projects
### Cleanup
- `clean` - Clean build artifacts
- `clean:all` - Clean everything including node_modules
### Database
- `prisma:generate` - Generate Prisma client
- `prisma:migrate` - Run database migrations
- `prisma:studio` - Open Prisma Studio
## 🛠️ Scripts Directory
The `scripts/` directory contains utility scripts:
- `install-all.sh` - Install all dependencies
- `run-dev.sh` - Run all development servers
- `add-package.sh` - Add package to a project
- `remove-package.sh` - Remove package from a project
- `clean-all.sh` - Clean all build artifacts
Make scripts executable:
```bash
chmod +x scripts/*.sh
```
## 📚 Project-Specific Documentation
- [Backend Setup Guide](./backend/SETUP_GUIDE.md)
- [Backend Architecture](./backend/ARCHITECTURE.md)
- [Web Progress](./web/WEB_PROGRESS.md)
## 🤝 Contributing
1. Install dependencies: `npm run install:all`
2. Start development: `npm run dev:all`
3. Make your changes
4. Run tests: `npm test`
5. Run linter: `npm run lint:fix`
## 📄 License
ISC
# gitgram