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>
629 lines
12 KiB
Markdown
629 lines
12 KiB
Markdown
# 🚀 Gitgram
|
|
|
|
**Instagram-like social platform for developers** - Share projects, connect through code, and build your developer network.
|
|
|
|
[]()
|
|
[]()
|
|
[]()
|
|
[]()
|
|
|
|
**🎉 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
|