958 lines
85 KiB
Markdown
958 lines
85 KiB
Markdown
# gitgram-ai Single Source Plan (v1)
|
||
|
||
Last updated: 2026-06-21
|
||
|
||
## The Mission
|
||
|
||
Git is 20 years old. GitHub is a web UI bolted on top.
|
||
Neither was built for AI agents generating 35 PRs a day,
|
||
social-first development, or deterministic workflow restore.
|
||
|
||
**GitGram is the social layer for GitHub repositories.** Every repository can
|
||
become a social account with posts, reels, stories, team photos, product videos,
|
||
screenshots, followers, and publishing workflows. GitGram uses GitHub APIs and
|
||
webhooks; it does not replace Git hosting, repository permissions, object
|
||
storage, refs, packfiles, or the Git wire protocol.
|
||
|
||
**AITM is deterministic workflow time travel for AI coding.** It captures and
|
||
restores agent actions, context, messages, tool calls, and checkpoints. It does
|
||
not claim to implement or replace Git. The separate Rust Git Forge product owns
|
||
the future Rust Git implementation and self-hostable forge boundary.
|
||
|
||
See `INTEGRATION_PLAN.md` for how the 8 cloned external repos
|
||
get merged into the actual product source trees.
|
||
|
||
Launch operations note (2026-05-09):
|
||
- The canonical launch contract is now the manual single-host runbook in `docs/runbook.md`.
|
||
- Historical references in this file to Vercel, Railway, or unfinished GitHub deploy workflows should be treated as planning notes, not launch instructions.
|
||
|
||
Reference intake note (2026-05-12):
|
||
- `docs/can be fork.md` is the maintained reference-clone inventory for external upstream repos under `external/`.
|
||
- Launch-critical external reference adoption is complete; this file remains the canonical execution plan.
|
||
|
||
## 1) Purpose
|
||
|
||
This document is the canonical execution plan for v1. It merges:
|
||
- Product/architecture decisions from `NORTH_STAR_PRD_ARCHITECTURE_V1.md`
|
||
- Delivery sequencing from `PLAN.md`
|
||
|
||
If any document conflicts with this one, this plan wins for implementation order.
|
||
|
||
## 2) Product Scope (Locked)
|
||
|
||
Products:
|
||
- `gitgram`: repository-first social network for developers (posts, reels, stories, comments, reactions, follows, trending).
|
||
- `aitimemachine` (AITM): deterministic restore and timeline system for AI coding workflows.
|
||
|
||
Out of scope for v1:
|
||
- Enterprise SSO/SAML hardening beyond scaffolding.
|
||
- Autonomous research/oracle workflows as primary UX.
|
||
- Private repo ingest without explicit legal and security controls.
|
||
|
||
## 3) Architecture and Policy Decisions (Locked)
|
||
|
||
1. Source of truth:
|
||
- Backend DB + object storage are authoritative.
|
||
- Local `.aitimemachine/` is cache/offline buffer only.
|
||
|
||
2. Storage model:
|
||
- `blobs`, `trees`, `checkpoints`, precomputed `diffs`, plus linked `messages`, `tool_calls`, `contexts`.
|
||
|
||
3. Capture model per AI action:
|
||
- `before_action` checkpoint.
|
||
- tool call metadata + initiating message link.
|
||
- `after_action` checkpoint.
|
||
- diff generation/classification.
|
||
- optional async indexing/embeddings.
|
||
|
||
4. Privacy and training:
|
||
- Training export is opt-in per workspace/org.
|
||
- Default is operational capture only.
|
||
- Redaction required before export.
|
||
|
||
5. Security minimums:
|
||
- Tenant isolation.
|
||
- Scoped auth and per-project authorization.
|
||
- Encryption at rest/in transit.
|
||
- Audit logs for restore/export/delete.
|
||
- Retention + hard-delete workflows.
|
||
- PII/secret redaction before training export.
|
||
|
||
## 4) Current State (As of 2026-03-17)
|
||
|
||
- Both products are **fully implemented, compiled, tested, and production-ready** at the code level.
|
||
- All core features verified end-to-end (see Section 4a and 4b below).
|
||
- Payment provider migrated from Stripe to Polar.sh (Stripe unavailable in Turkey).
|
||
- Only deployment/infrastructure work remains for launch.
|
||
|
||
### Completed (prior to 2026-03-02):
|
||
- Route duplication removed in Gitgram.
|
||
- Socket service migration completed.
|
||
- Logging standardized with Winston.
|
||
- API response helper foundation added in AITM.
|
||
- Disk-full handling added in AITM ContentStore writes.
|
||
- MCP rate limiting added.
|
||
- Abuse detection moved to Redis-backed store (with fallback).
|
||
- AITM backend URL alignment fixes completed.
|
||
- TypeScript strict mode confirmed in both backends.
|
||
|
||
### Completed (2026-03-02 to 2026-03-09):
|
||
|
||
**Rebranding & Core Fixes:**
|
||
- AITM rebranded from legacy "gitmind" references across CLI, API server, extensions.
|
||
- CLI modularized from monolithic `cli-v2.ts` into per-command files under `src/cli/`.
|
||
- MCP server consolidated from 3 separate packages into single unified package.
|
||
- AITM API server error responses standardized via `wrapErrorMessage()` middleware.
|
||
|
||
**Test Coverage (1130+ tests, all passing):**
|
||
- AITM Core: 520/520 (35 suites) — CLI commands, smart-restore, core engine.
|
||
- AITM API Server: 538/538 + 19 skip (45 suites) — all integration/service tests.
|
||
- AITM VS Code Extension: 62/62.
|
||
- Gitgram Web: 72/72 (7 suites) — auth, post, user, component tests.
|
||
- Test infrastructure: fixed supertest/listen mock conflict, fixed error format across 18 test files.
|
||
|
||
**Security Hardening:**
|
||
- Advertisement endpoints: added rate limiting, UUID validation, ad-exists check before tracking.
|
||
- Advertisement creation: added input validation (URL, budget, type, dates, content length).
|
||
- Repository claim: added GitHub ownership verification via Octokit permissions check.
|
||
- Webhook signature: fixed timing-unsafe comparison to use `crypto.timingSafeEqual`.
|
||
- Gitgram auth already uses httpOnly cookies (JWT primary method).
|
||
- AITM OAuth: CSRF state tokens verified in SSO tests.
|
||
|
||
**Type Safety:**
|
||
- AITM API server `db` export: fixed root cause `any` → `NeonHttpDatabase<typeof schema>` (eliminated ~30 implicit any errors).
|
||
- Fixed 21 explicit `any` types in AITM services (retention, webhookDelivery, sessionManager, data-pipeline).
|
||
- Fixed `any` types in Gitgram paymentService, aitmService, mobile storeService, messages, notifications.
|
||
- All type checks pass with zero errors across all products.
|
||
|
||
**Bug Fixes:**
|
||
- Mobile store: fixed call to non-existent `getProducts()` → `getItems()`.
|
||
- Mobile create post: replaced stubbed console.log handler with real `postService.createPost`.
|
||
- Docker: fixed postgres version, port mappings, added missing env vars to AITM Dockerfile.
|
||
- Removed dead code (unused `mock.ts` service file).
|
||
|
||
**CI/CD (already in place):**
|
||
- 7 GitHub Actions workflows: ci.yml, tests.yml, integration-tests.yml, smoke-tests.yml, migrations.yml, verify-production-db.yml, openapi-validation.yml.
|
||
- `.env.example` files for all products (root + per-package).
|
||
|
||
### Completed (2026-03-17):
|
||
|
||
**Payment Migration:**
|
||
- Stripe → Polar.sh across entire codebase (backend, frontend, mobile, docs).
|
||
- `@polar-sh/sdk@0.46.4` replaces `stripe` package.
|
||
- Webhook verification uses `validateEvent` from `@polar-sh/sdk/webhooks` (Standard Webhooks spec).
|
||
- Prisma schema: `stripeCustomerId`/`stripeSubscriptionId` → `polarCustomerId`/`polarSubscriptionId`.
|
||
- Env vars: `POLAR_ACCESS_TOKEN`, `POLAR_WEBHOOK_SECRET`, `POLAR_PREMIUM_PRODUCT_ID`, `POLAR_CREATOR_PRODUCT_ID`, `POLAR_MODE`.
|
||
|
||
### Completed (2026-05-12):
|
||
|
||
**Payment Launch Alignment From Local Polar Source:**
|
||
- Added `docs/polar-payment-setup.md` using the cloned `external/polar` docs/source as the billing reference.
|
||
- Confirmed service integrations should use Polar Organization Access Tokens, not OAuth/OpenID Connect.
|
||
- Confirmed sandbox and production are isolated, and both Gitgram and AITM now honor `POLAR_MODE`.
|
||
- AITM website billing routes now share a `POLAR_MODE`-aware Polar client instead of assuming one environment.
|
||
- AITM API webhook verification now uses the SDK validator path and accepts both camelCase and snake_case event fields.
|
||
- Gitgram backend webhook handling now uses the SDK validator flow through a CommonJS-compatible wrapper instead of ad hoc event-field assumptions.
|
||
- AITM API env validation now includes `POLAR_MODE`, and remaining env examples were updated to document it.
|
||
- `npm run verify:launch` is back to failing only on real missing secrets / placeholder values, not on Polar contract mismatches.
|
||
- Launch tooling now supports env-specific operator files such as `.env.gitgram.staging` and `.env.aitm-api.staging`, so staging can use Polar sandbox values without conflicting with production `POLAR_MODE=production`.
|
||
- Dedicated Neon databases now exist for Gitgram and AITM staging/production, and the root env files now contain real DB URLs plus generated app-owned secrets instead of placeholders.
|
||
- Launch readiness is now split into `core` versus `full` integration gates, so deployability is no longer blocked on GitHub OAuth, Polar, Resend, or Sentry being configured on day zero.
|
||
|
||
### Completed (2026-05-13):
|
||
|
||
**Reference Clone Adoption Into Product Code:**
|
||
- Gitgram adopted `external/repo2txt` / `external/repo-to-text` into a shipped repo-to-text surface: backend export endpoint, short-path text page, raw text route, queryable export sizing, and discovery-surface `Text` / `Raw` links.
|
||
- Gitgram web now has real Playwright coverage for the public repo-routing and repo-to-text surface: short-path `/:owner/:repo`, legacy `github/.../text` canonicalization, queryable export sizing, and repo-page → text-view navigation.
|
||
- AITM MCP adopted `external/a2a-js` into a real A2A contract layer: canonical `message/send` handling with legacy `tasks/send` compatibility, protocol-versioned agent cards, spec-shaped task responses, and a repeatable `scripts/a2a-smoke-test.sh` verification path.
|
||
- AITM MCP adopted the core `external/pal-mcp-server` patterns: real stable-vs-experimental tool policy, `DISABLED_TOOLS` shutdown support, aligned A2A/HTTP capability reporting, modular category-based tool registration instead of a monolithic `src/index.ts`, shared tool-annotation/output helpers, and declarative `createToolRegistrar` / `defineTool` registration helpers across the extracted tool modules.
|
||
- AITM MCP adopted `external/context7` transport-hardening patterns end to end: request-scoped HTTP context, stable request IDs exposed via `X-Request-Id`, structured parse/protocol error mapping, per-request logging across MCP/A2A/discovery/health routes, and nested request-ID propagation from A2A into the internal `/mcp` bridge.
|
||
- Launch readiness now includes real CLI/MCP tarball inspection for npm publishability, not only `npm pack --dry-run`.
|
||
|
||
### 4a) AITM Feature Verification
|
||
|
||
All time-travel features verified as fully implemented:
|
||
- **Checkpoint creation**: SHA256 content-addressable storage, lazy file reading.
|
||
- **Restore**: Atomic 3-phase (delete/restore/context), auto-backup, rollback on failure.
|
||
- **Diff**: 3 algorithms (Myers, Patience, Histogram), unified output.
|
||
- **Cat**: View any file from any past checkpoint.
|
||
- **Storage**: `.aitimemachine/store/` loose objects + pack files + SQLite metadata.
|
||
- **Cloud Sync**: Checkpoint/blob upload with quota, efficient dedup via hash checking.
|
||
- **Web UI**: 6-step restore flow with preview, selective restore, undo.
|
||
- **VS Code Extension**: List/create/restore/diff commands with autocomplete.
|
||
- **API Server**: Full REST API for restore, manifest, blobs, batch operations.
|
||
|
||
### 4b) Gitgram Feature Verification
|
||
|
||
All 12 core social features verified as fully implemented (backend + frontend + database):
|
||
- Auth (JWT + 2FA + GitHub/Google OAuth)
|
||
- Posts (media, code snippets, mentions, hashtags)
|
||
- Feed (algorithm-driven, personalized)
|
||
- Comments (nested) & Likes
|
||
- User Profiles (avatar, bio, settings)
|
||
- Follow/Unfollow (with notifications, private account support)
|
||
- GitHub Integration (real Octokit OAuth, repo sync, claiming)
|
||
- Reels (video upload, comments, reactions)
|
||
- Stories (24hr expiry, analytics, highlights)
|
||
- Direct Messages (WebSocket real-time, group chat, read receipts)
|
||
- Search (multi-type, advanced filters, relevance ranking)
|
||
- Notifications (WebSocket real-time, push support)
|
||
|
||
### 4c) App-Code Stub / Placeholder Audit (2026-05-12)
|
||
|
||
This audit overrides earlier "fully implemented" wording for the specific surfaces below. These routes/components exist in product code, but some were empty shells, wired to wrong endpoints, or claimed features that are not backed by schema/routes yet.
|
||
|
||
**Fixed in current remediation batches (2026-05-12)**
|
||
- `gitgram/web/app/explore/trending/page.tsx`
|
||
- Replaced the empty shell with live trending posts, repos, and creators.
|
||
- `gitgram/web/services/storyService.ts` and story pages under `gitgram/web/app/story/**`
|
||
- Rewired to the real `/api/v1/stories/*` contract, including archive, analytics, replies, grouped feeds, and reaction summary behavior.
|
||
- `gitgram/web/app/story/highlights/**` and `gitgram/web/app/story/settings/page.tsx`
|
||
- Backed by real Prisma models and backend routes for named highlights plus `allowReplies` / `hideFrom` settings.
|
||
- `gitgram/web/app/reel/[id]/page.tsx`, `gitgram/web/app/reel/[id]/likes/page.tsx`, and `gitgram/web/app/reel/[id]/share/page.tsx`
|
||
- Normalized against real like/share contracts and the added `GET /api/v1/reels/:id/likes` backend route.
|
||
- `gitgram/web/app/reel/[id]/music/page.tsx`
|
||
- Replaced the fake `/v1/reels/music` call with real `/api/v1/music/*` search plus `POST/DELETE /api/v1/reels/:id/music`.
|
||
- `gitgram/web/app/reel/[id]/reactions/page.tsx` and `gitgram/mobile/app/reel/[id]/reactions.tsx`
|
||
- Made truthful by presenting reel likes instead of pretending typed reel reactions exist.
|
||
- `gitgram/backend/src/controllers/reelsController.ts`, `gitgram/backend/prisma/schema.prisma`, and reel players on web/mobile
|
||
- Reel effect and trim metadata now persist (`effectId`, `trimStart`, `trimEnd`, `thumbnailTime`) and the actual players honor those saved values instead of dropping them after publish.
|
||
- `gitgram/web/app/reel/[id]/effects/page.tsx`
|
||
- Replaced the fake effects endpoint call with a real view over the persisted reel effect metadata.
|
||
- `gitgram/web/app/reel/drafts/page.tsx`
|
||
- Removed the fake drafts endpoint assumption; the route now 404s instead of pretending reel drafts exist.
|
||
- `gitgram/mobile/app/reel/[id]/music.tsx`, `gitgram/mobile/app/(modals)/create-reel.tsx`, and `gitgram/mobile/app/create/reel.tsx`
|
||
- Real music selection now persists through the reel editor flow and saves through the reel music contract instead of fake success fallbacks.
|
||
- `gitgram/mobile/app/(modals)/create-reel.tsx`, `gitgram/mobile/app/create/reel.tsx`, and `gitgram/mobile/components/Reel/ReelTrimEditor.tsx`
|
||
- Replaced the disabled trim placeholder with real persisted trim controls shared across both mobile reel creation flows, and added real device-camera capture plus library import instead of library-only intake.
|
||
- `gitgram/mobile/app/map/explore.tsx`
|
||
- Replaced the broken map placeholder/no-op filter screen with a real project explorer backed by trending repositories, working language filters, optional location-aware map context, and an honest explanation that repository coordinates are not stored yet.
|
||
- `gitgram/web/app/reels/create/page.tsx`
|
||
- Removed non-persisted text/code overlay authoring, added real saved effect selection, and limited the UI to the reel fields the backend actually stores today.
|
||
|
||
**Remaining web placeholder-backed surfaces**
|
||
- None currently identified in the active remediation scope.
|
||
|
||
**Remaining mobile placeholder-backed surfaces**
|
||
- `gitgram/mobile/app/reel/drafts.tsx`
|
||
- Now explicitly reports that reel drafts are unsupported rather than calling fake endpoints; real reel draft persistence still does not exist.
|
||
|
||
**Immediate remediation batch — NEXT**
|
||
- Decide whether reel drafts are a real product requirement or should stay removed until backed by schema/routes.
|
||
- Decide whether dedicated in-app reel recording is required beyond the now-working device camera capture path.
|
||
- Decide whether text/code overlays on reels are a real persisted feature worth adding back later with schema/routes and rendering support.
|
||
|
||
**Queued after current batch**
|
||
- Align any future reel overlay authoring with a persisted backend contract before surfacing it again on mobile.
|
||
|
||
### 4d) External Reference Adoption Status
|
||
|
||
This section summarizes launch-state reference adoption. No launch-critical reference adoption remains; future uses below are post-launch enhancements only if the product needs them.
|
||
|
||
| Reference | Product | Status | Active plan |
|
||
|---|---|---|---|
|
||
| `repo2txt` + `repo-to-text` | Gitgram | `adopted` | No launch-critical follow-up remains. Revisit only if Gitgram adds compose/share/import workflows that need deeper repo-text embedding. |
|
||
| `a2a-js` | AITM MCP | `adopted` | No launch-critical follow-up remains. Revisit only if AITM adds true A2A streaming or additional task lifecycle methods beyond the current blocking `message/send` bridge. |
|
||
| `context7` | AITM MCP | `adopted` | No launch-critical follow-up remains. Revisit only if AITM later needs deeper user/auth context propagation across downstream remote calls. |
|
||
| `pal-mcp-server` | AITM MCP | `adopted` | No launch-critical follow-up remains. Revisit only if the MCP surface expands enough to justify automatic output-schema or capability-family generation. |
|
||
|
||
## 5) Unified Delivery Sequence
|
||
|
||
The sequencing below resolves prior ambiguity:
|
||
- Architecture/security gates remain mandatory.
|
||
- Launch blockers are prioritized first because they prevent external usability.
|
||
- Feature acceleration continues only after launch unblockers are complete.
|
||
|
||
### Stage A: Launch Unblockers (Immediate) — IN PROGRESS
|
||
|
||
Goal: make both products externally usable.
|
||
|
||
Stage A readiness helpers now in repo:
|
||
- `docs/runbook.md` remains the canonical manual launch path.
|
||
- `scripts/verify-launch-readiness.sh` is the one-command gate for PM2, env file presence, secret contract validation, and AITM package publishability.
|
||
- `npm run verify:aitm-packages` now goes beyond `npm pack --dry-run`: it also creates real CLI/MCP tarballs, unpacks them, and verifies published bin paths, packaged files, and the MCP dependency on `@gitgram/timemachine`.
|
||
- `npm run verify:a2a` is the standards smoke for AITM's HTTP A2A card and `message/send`/`tasks/send` behavior.
|
||
- `npm run verify:launch` runs the default `core` gate.
|
||
- `npm run verify:launch:full` runs the stricter third-party integration gate.
|
||
- `scripts/deploy-launch.sh` is the PM2-aligned scripted deploy path for Gitgram and AITM.
|
||
- `scripts/verify-public-launch.sh` is the public-domain smoke pass for `gitgram.app` and AITM endpoints after DNS/nginx cutover.
|
||
|
||
#### A1. Publish AITM packages to npm — TODO
|
||
|
||
Both packages are fully configured for publishing. CLI must be published first (MCP depends on it).
|
||
|
||
**Step-by-step publish plan:**
|
||
|
||
1. **Pre-publish checks:**
|
||
```bash
|
||
cd aitimemachine && npm run build && npm test # verify clean build + 520 tests pass
|
||
cd mcp && npm run build # verify MCP builds
|
||
```
|
||
|
||
2. **Publish CLI first** (`@gitgram/timemachine@2.0.0`):
|
||
```bash
|
||
cd aitimemachine
|
||
npm publish --access public
|
||
```
|
||
- Package: `@gitgram/timemachine`
|
||
- Bin: `aitm`, `aitimemachine`
|
||
- Entry: `lib/cli-v2.js`
|
||
- Files: `lib/**/*`, `README.md`, `LICENSE`
|
||
- Hooks: `prepack` → build, `prepublishOnly` → build + test
|
||
|
||
3. **Verify CLI install:**
|
||
```bash
|
||
npx @gitgram/timemachine --version
|
||
mkdir /tmp/aitm-test && cd /tmp/aitm-test
|
||
npx @gitgram/timemachine init
|
||
npx @gitgram/timemachine checkpoint --message "test"
|
||
```
|
||
|
||
4. **Publish MCP server** (`@gitgram/timemachine-mcp@2.0.0`):
|
||
```bash
|
||
cd aitimemachine/mcp
|
||
npm publish --access public
|
||
```
|
||
- Package: `@gitgram/timemachine-mcp`
|
||
- Bin: `aitm-mcp`, `aitm-mcp-client`
|
||
- Entry: `dist/index.js`
|
||
- Depends on: `@gitgram/timemachine@^2.0.0` (must be on npm first)
|
||
- Files: `dist/**/*`, `server.json`, `README.md`, `LICENSE`
|
||
|
||
5. **Verify MCP install:**
|
||
```bash
|
||
npx @gitgram/timemachine-mcp --help
|
||
```
|
||
|
||
6. **Automated releases (future tags):**
|
||
- CI workflow (`aitimemachine/.github/workflows/ci.yml`) has a release job
|
||
- Triggered on tag push matching `v*`
|
||
- Uses GitHub secret `NPM_TOKEN`, passed to npm as `NODE_AUTH_TOKEN`
|
||
- Current workflow publishes `@gitgram/timemachine`; MCP publish still requires a manual step until automation is aligned
|
||
|
||
**npm cost: $0** (public packages are free)
|
||
|
||
#### A2. Configure production secrets — TODO
|
||
|
||
| Secret | Product | Source |
|
||
|--------|---------|--------|
|
||
| `POLAR_ACCESS_TOKEN` | Gitgram | polar.sh > Organization Settings > Access Tokens |
|
||
| `POLAR_WEBHOOK_SECRET` | Gitgram | polar.sh > Organization Settings > Webhooks |
|
||
| `POLAR_PREMIUM_PRODUCT_ID` | Gitgram | polar.sh > Products (create Premium $9.99/mo) |
|
||
| `POLAR_CREATOR_PRODUCT_ID` | Gitgram | polar.sh > Products (create Creator $19.99/mo) |
|
||
| `POLAR_ACCESS_TOKEN` | AITM | polar.sh (same or separate org) |
|
||
| `GITHUB_CLIENT_ID` | Gitgram | github.com/settings/developers |
|
||
| `GITHUB_CLIENT_SECRET` | Gitgram | github.com/settings/developers |
|
||
| `GOOGLE_CLIENT_ID` | Gitgram | console.cloud.google.com |
|
||
| `GOOGLE_CLIENT_SECRET` | Gitgram | console.cloud.google.com |
|
||
| `CLERK_SECRET_KEY` | AITM | dashboard.clerk.com |
|
||
| `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | AITM | dashboard.clerk.com |
|
||
| `RESEND_API_KEY` | Both | resend.com/api-keys |
|
||
| `SENTRY_DSN` (x2) | Both | sentry.io (one project per product) |
|
||
| `DATABASE_URL` | Gitgram | Neon console |
|
||
| `DATABASE_URL` | AITM | Neon console |
|
||
| `REDIS_URL` | Gitgram | Upstash console |
|
||
| `AWS_ACCESS_KEY_ID` | Gitgram | AWS IAM |
|
||
| `AWS_SECRET_ACCESS_KEY` | Gitgram | AWS IAM |
|
||
| `JWT_SECRET` | Gitgram | Generate: `openssl rand -base64 48` |
|
||
| `JWT_REFRESH_SECRET` | Gitgram | Generate: `openssl rand -base64 48` |
|
||
|
||
#### A3. Deploy production baseline — TODO
|
||
|
||
- Provision VPS (Hetzner CX32 recommended: 4 vCPU, 8 GB RAM, 80 GB NVMe).
|
||
- Configure DNS records (A/AAAA) for `gitgram.app`, `api.gitgram.app`, `aitm.gitgram.app`.
|
||
- TLS via Let's Encrypt / Caddy auto-HTTPS.
|
||
- Build the services and start them under PM2 on the launch host.
|
||
- Verify health endpoints and monitoring.
|
||
|
||
#### A4. Run E2E smoke tests — PARTIAL
|
||
|
||
- ~~AITM install/init/checkpoint/timeline path.~~ **DONE** — covered by 520 CLI tests.
|
||
- ~~Gitgram public repo routing + repo-to-text path.~~ **DONE** — covered by focused Playwright browser tests with mocked repository/export APIs.
|
||
- Gitgram signup/oauth/post/comment/notification path. **PARTIAL** — auth/post/comment/notification mocks, selectors, and a focused Playwright spec now exist; backend notification detail routes and checkpoint-aware post flows are wired. Local `next dev` browser execution still blanks on protected client pages, so deployment-backed verification is still required before treating this as closed.
|
||
|
||
Exit criteria:
|
||
- Both products are installable/deployable.
|
||
- All health checks pass.
|
||
- End-to-end flows complete without critical failure.
|
||
|
||
### Stage B: Security Closure — COMPLETE
|
||
|
||
1. ~~JWT storage migration to httpOnly cookies in Gitgram.~~ **DONE**
|
||
2. ~~OAuth callback URL hardening + redirect validation + CSRF state checks in AITM.~~ **DONE**
|
||
3. ~~Complete API response helper migration in AITM for consistent error/success semantics.~~ **DONE**
|
||
4. ~~Validate retention/delete/export audit paths in staging.~~ **DONE**
|
||
|
||
Additional security work completed beyond original plan:
|
||
- Advertisement tracking endpoints: rate limiting + ad-exists validation.
|
||
- Repository claim: GitHub ownership verification via Octokit.
|
||
- Webhook signature: timing-safe comparison fix.
|
||
- Input validation added on advertisement and claim routes.
|
||
|
||
Exit criteria: **ALL MET**
|
||
|
||
### Stage C: Reliability and Code Quality — COMPLETE
|
||
|
||
1. ~~Split AITM `cli-v2.ts` into modular command files.~~ **DONE**
|
||
2. ~~Reduce `any` usage in AITM by priority surfaces.~~ **DONE**
|
||
3. ~~Add Gitgram frontend unit/integration tests.~~ **DONE** — 72 tests.
|
||
4. Add Playwright critical-path E2E and CI gating. **PARTIAL** — repo routing/text coverage is in place and gated in CI. A second focused auth/comment/notification browser spec and CI job wiring are added, but protected-page browser verification still needs production-style validation because the local dev-server path is not stable enough to close the item.
|
||
|
||
Exit criteria: **3 of 4 MET** (repo-route coverage and CI gate added; broader protected live-flow coverage is implemented but not fully verified yet)
|
||
|
||
### Stage D: Cross-Product Integration — PARTIAL / POST-LAUNCH (New Feature Coding)
|
||
|
||
Note: This is **post-launch enhancement** work, not a gap in existing v1 functionality.
|
||
|
||
1. ~~Add checkpoint linkage in Gitgram posts (`aitm_checkpoint_id` / `checkpointRef`).~~ **PARTIAL** — checkpoint-aware post creation now works through Gitgram compose, the backend accepts checkpoint metadata, and checkpoint-only post publishing is covered by service/unit validation.
|
||
2. ~~Ship AITM "share as post" flow (connect existing UI to backend).~~ **PARTIAL** — AITM context replay now deep-links into Gitgram compose for post and change-story publishing with checkpoint/project context carried through.
|
||
3. ~~Add "Change Story" post type from AITM diffs.~~ **PARTIAL** — Gitgram compose accepts AITM diff/query params, Change Story publishing is live, and Creator Studio exposes repo-linked Change Story entry points. Trend-side surfacing is still open.
|
||
4. Launch trend ranking combining GitHub + platform social signals. **TODO**
|
||
|
||
### Stage E: Intelligence and Growth — PARTIAL / POST-LAUNCH (New Feature Coding)
|
||
|
||
Note: This is **post-launch enhancement** work, not required for v1.
|
||
|
||
1. ~~Semantic search over checkpoint/code history.~~ **PARTIAL** — AITM website now has a Semantic Search dashboard backed by new internal knowledge-base search/stats/artifact routes and passing integration coverage on the API layer.
|
||
2. ~~Training export pipeline with opt-in + redaction + audit traceability.~~ **PARTIAL** — AITM website now has Training Exports controls, project-level consent toggles, internal pipeline routes, and passing integration coverage for consent/pipeline happy paths plus denial enforcement. End-to-end artifact generation on deployed infra is still open.
|
||
3. ~~Creator tooling for repo owners (story/reel workflows).~~ **PARTIAL** — Gitgram Creator Studio now exposes repository creator tools, direct repo text/export entry points, post/change-story shortcuts, and AITM setup links. Expanded story/reel growth workflows remain open.
|
||
|
||
## 6) Priority Ticket Backlog (Ordered)
|
||
|
||
P0 (must complete first — deployment):
|
||
- Publish AITM CLI and MCP packages to npm.
|
||
- Production secrets setup for both products.
|
||
- Production infra deploy + DNS/TLS + monitoring.
|
||
- End-to-end smoke verification on live environment.
|
||
|
||
~~P1~~ **COMPLETE:**
|
||
- ~~Gitgram auth token migration to httpOnly cookies.~~ Done.
|
||
- ~~AITM OAuth callback and redirect hardening.~~ Done.
|
||
- ~~AITM response helper migration completion.~~ Done.
|
||
- ~~Retention/delete/export audit verification.~~ Done.
|
||
|
||
~~P2~~ **COMPLETE:**
|
||
- ~~AITM CLI modularization.~~ Done.
|
||
- ~~AITM `any` reduction campaign.~~ Done.
|
||
- ~~Gitgram frontend testing stack and CI enforcement.~~ Done.
|
||
|
||
P3 (post-deploy — new feature coding + testing):
|
||
- Finish deployment-backed verification for protected Gitgram auth/post/comment/notification browser flows.
|
||
- Complete trend ranking / discovery surfacing for checkpoint-linked posts and Change Story content (Stage D).
|
||
- Harden semantic search relevance and deployed training-export artifact generation (Stage E).
|
||
- Expand Creator Studio beyond repo quick actions into richer story/reel growth tooling (Stage E).
|
||
|
||
## 7) Infrastructure Cost Breakdown
|
||
|
||
### Per-Service Pricing (Monthly)
|
||
|
||
| Service | Product | Plan | Monthly Cost | Notes |
|
||
|---------|---------|------|-------------|-------|
|
||
| **npm** | AITM | Public packages | **$0** | Unlimited free public packages |
|
||
| **Hetzner VPS** | Both | CX32 (4 vCPU, 8 GB, 80 GB) | **~$7** | Docker compose for Gitgram backend + AITM API. ~$8/mo after Apr 2026 price increase |
|
||
| **Neon PostgreSQL** | Gitgram | Free → Launch | **$0–$5** | Free: 100 CU-hrs, 0.5 GB. Launch: $5/mo min, storage $0.35/GB-mo |
|
||
| **Neon PostgreSQL** | AITM | Free → Launch | **$0–$5** | Separate project. Same tiers |
|
||
| **Vercel** | Both (web) | Hobby (free) | **$0** | Free for non-commercial. Pro: $20/user/mo when needed |
|
||
| **Polar.sh** | Both | Transaction fees only | **$0 base** | 4% + $0.40 per transaction. No monthly fee. MoR handles taxes |
|
||
| **Clerk** | AITM | Free | **$0** | Free up to 50K MAU. Pro: $20/mo when needed |
|
||
| **Resend** | Both | Free | **$0** | 3,000 emails/mo free. Pro: $20/mo for 50K emails |
|
||
| **Sentry** | Both | Developer (free) | **$0** | 5K errors/mo, 1 user. Team: $26/mo when needed |
|
||
| **Upstash Redis** | Gitgram | Free | **$0** | 256 MB, 500K commands/mo free |
|
||
| **AWS S3** | Gitgram | Pay-as-you-go | **~$1–5** | $0.023/GB storage + $0.09/GB egress (first 100 GB free) |
|
||
| **Domain** | Both | .app domain | **~$2/mo** | ~$20–25/year for `.app` domain |
|
||
| **GitHub Actions** | Both | Free tier | **$0** | 2,000 min/mo free for public repos |
|
||
|
||
### Cost Scenarios
|
||
|
||
#### Minimum Launch (Free Tiers Only)
|
||
|
||
| Item | Cost |
|
||
|------|------|
|
||
| Hetzner CX32 | $7/mo |
|
||
| Domain (.app) | $2/mo |
|
||
| Everything else on free tiers | $0 |
|
||
| **Total** | **~$9/mo** |
|
||
|
||
#### Small Scale (100 users, light usage)
|
||
|
||
| Item | Cost |
|
||
|------|------|
|
||
| Hetzner CX32 | $7/mo |
|
||
| Neon Launch x2 | $10/mo |
|
||
| AWS S3 (10 GB) | $1/mo |
|
||
| Domain | $2/mo |
|
||
| Vercel Hobby | $0 |
|
||
| Clerk Free | $0 |
|
||
| Resend Free | $0 |
|
||
| Sentry Free | $0 |
|
||
| Upstash Free | $0 |
|
||
| Polar.sh (est. 20 txns) | ~$12/mo (fee on revenue) |
|
||
| **Total infra** | **~$20/mo** (+ Polar fees on revenue) |
|
||
|
||
#### Growth (1,000 users, moderate usage)
|
||
|
||
| Item | Cost |
|
||
|------|------|
|
||
| Hetzner CX42 (8 vCPU, 16 GB) | $18/mo |
|
||
| Neon Scale x2 | $40/mo |
|
||
| AWS S3 (100 GB + egress) | $12/mo |
|
||
| Vercel Pro (1 seat) | $20/mo |
|
||
| Clerk Pro | $20/mo |
|
||
| Resend Pro | $20/mo |
|
||
| Sentry Team | $26/mo |
|
||
| Upstash Pay-as-you-go | $5/mo |
|
||
| Domain | $2/mo |
|
||
| Polar.sh (est. 200 txns) | ~$120/mo (fee on revenue) |
|
||
| **Total infra** | **~$163/mo** (+ Polar fees on revenue) |
|
||
|
||
### Polar.sh Revenue Model
|
||
|
||
Polar.sh charges **4% + $0.40 per transaction** (no monthly fee). Revenue examples:
|
||
|
||
| Subscribers | Plan | Gross Revenue | Polar Fee (4% + $0.40) | Net Revenue |
|
||
|-------------|------|--------------|----------------------|-------------|
|
||
| 10 | Premium ($9.99) | $99.90/mo | $4.40 + $4.00 = $8.40 | $91.50/mo |
|
||
| 10 | Creator ($19.99) | $199.90/mo | $8.00 + $4.00 = $12.00 | $187.90/mo |
|
||
| 50 | Mixed | ~$750/mo | ~$50 | ~$700/mo |
|
||
| 100 | Mixed | ~$1,500/mo | ~$100 | ~$1,400/mo |
|
||
| 500 | Mixed | ~$7,500/mo | ~$500 | ~$7,000/mo |
|
||
|
||
Polar is the Merchant of Record — they handle tax calculation, collection, and remittance globally.
|
||
|
||
## 8) KPIs
|
||
|
||
Product:
|
||
- Weekly active developers.
|
||
- Restore actions per active AITM user.
|
||
- Social interactions per repository page.
|
||
- 7-day retention after first restore.
|
||
|
||
System:
|
||
- Restore success rate and latency percentiles.
|
||
- Diff generation latency.
|
||
- Checkpoint ingestion throughput.
|
||
- Sync lag (local cache to backend).
|
||
|
||
Safety:
|
||
- Consent coverage.
|
||
- Redaction precision/recall.
|
||
- Mean deletion-request resolution time.
|
||
|
||
## 9) Governance Rule
|
||
|
||
Before starting any new feature stream, verify:
|
||
1. It does not violate Section 3 locked decisions.
|
||
2. It does not bypass P0/P1 launch and security gates.
|
||
3. It has measurable exit criteria tied to KPIs in Section 8.
|
||
|
||
## 10) Status Summary (2026-03-17)
|
||
|
||
| Stage | Status | Work Type |
|
||
|-------|--------|-----------|
|
||
| v1 Core Coding | **COMPLETE** | All features implemented and tested (1130+ tests passing) |
|
||
| Payment Migration | **COMPLETE** | Stripe → Polar.sh (all code, config, docs updated) |
|
||
| Stage A (Deploy) | **TODO** | npm publish (CLI + MCP), secrets, VPS, DNS/TLS, DB |
|
||
| Stage B (Security) | **COMPLETE** | All exit criteria met |
|
||
| Stage C (Quality) | **COMPLETE** | 3/4 met; Playwright deferred to post-deploy |
|
||
| Stage D (Cross-Product) | **PARTIAL / POST-LAUNCH** | Enhancement work; not a launch blocker |
|
||
| Stage E (Growth) | **PARTIAL / POST-LAUNCH** | Enhancement work; not a launch blocker |
|
||
|
||
**Bottom line:**
|
||
- Zero coding needed for v1 launch — only deployment/infrastructure remains.
|
||
- Minimum launch cost: **~$9/mo** (Hetzner + domain, everything else free tier).
|
||
- Stage D and E are post-launch enhancements, not v1 gaps.
|
||
|
||
Tests — All Passing
|
||
|
||
┌─────────────────┬───────────────────────┬───────────┐
|
||
│ Suite │ Tests │ Status │
|
||
├─────────────────┼───────────────────────┼───────────┤
|
||
│ AITM Core │ 520/520 │ PASS │
|
||
├─────────────────┼───────────────────────┼───────────┤
|
||
│ AITM API Server │ 538/538 (+19 skipped) │ PASS │
|
||
├─────────────────┼───────────────────────┼───────────┤
|
||
│ Gitgram Web │ 72/72 │ PASS │
|
||
├─────────────────┼───────────────────────┼───────────┤
|
||
│ Total │ 1,130 │ ALL GREEN │
|
||
└─────────────────┴───────────────────────┴───────────┘
|
||
|
||
npm Packages — Ready to Publish
|
||
|
||
┌───────────────────────────────┬─────────┬────────────────────────────────────────────────────────┐
|
||
│ Package │ Version │ Details │
|
||
├───────────────────────────────┼─────────┼────────────────────────────────────────────────────────┤
|
||
│ @gitgram/timemachine │ 2.0.0 │ CLI: aitm, aitimemachine. 23 commands, core engine │
|
||
├───────────────────────────────┼─────────┼────────────────────────────────────────────────────────┤
|
||
│ @gitgram/timemachine-mcp │ 2.0.0 │ MCP server: aitm-mcp. Depends on CLI ^2.0.0 │
|
||
└───────────────────────────────┴─────────┴────────────────────────────────────────────────────────┘
|
||
Polar.sh fee on $20 subscription
|
||
|
||
┌─────────────┬─────────────────┐
|
||
│ │ Per Transaction │
|
||
├─────────────┼─────────────────┤
|
||
│ Gross │ $20.00 │
|
||
├─────────────┼─────────────────┤
|
||
│ 4% fee │ -$0.80 │
|
||
├─────────────┼─────────────────┤
|
||
│ Fixed fee │ -$0.40 │
|
||
├─────────────┼─────────────────┤
|
||
│ You receive │ $18.80 │
|
||
└─────────────┴─────────────────┘
|
||
|
||
Scaled out:
|
||
|
||
┌─────────────┬──────────┬───────────┬────────────┐
|
||
│ Subscribers │ Gross/mo │ Polar Fee │ You Get │
|
||
├─────────────┼──────────┼───────────┼────────────┤
|
||
│ 1 │ $20 │ $1.20 │ $18.80 │
|
||
├─────────────┼──────────┼───────────┼────────────┤
|
||
│ 10 │ $200 │ $12.00 │ $188.00 │
|
||
├─────────────┼──────────┼───────────┼────────────┤
|
||
│ 50 │ $1,000 │ $60.00 │ $940.00 │
|
||
├─────────────┼──────────┼───────────┼────────────┤
|
||
│ 100 │ $2,000 │ $120.00 │ $1,880.00 │
|
||
├─────────────┼──────────┼───────────┼────────────┤
|
||
│ 500 │ $10,000 │ $600.00 │ $9,400.00 │
|
||
├─────────────┼──────────┼───────────┼────────────┤
|
||
│ 1,000 │ $20,000 │ $1,200.00 │ $18,800.00 │
|
||
└─────────────┴──────────┴───────────┴────────────┘
|
||
|
||
What each scenario includes
|
||
|
||
Minimum Launch — ~$9/mo
|
||
|
||
What you get:
|
||
- 1 VPS running both Gitgram backend + AITM API server (4 vCPU, 8 GB RAM)
|
||
- PostgreSQL with 0.5 GB storage per project (auto-scales to zero when idle)
|
||
- Redis with 256 MB cache, 500K commands/mo
|
||
- 3,000 emails/mo (password reset, notifications)
|
||
- 5K error tracking events/mo
|
||
- 50K auth users (AITM via Clerk)
|
||
- Frontend hosted on Vercel free tier
|
||
- Media stored locally on VPS (80 GB NVMe)
|
||
|
||
Limits you'll hit first:
|
||
- 0.5 GB database (enough for ~5K-10K users)
|
||
- No S3 (media on VPS disk, 80 GB cap)
|
||
- 3K emails/mo (enough for ~500 active users)
|
||
- No CDN, no custom email domain
|
||
- Vercel hobby = non-commercial only
|
||
|
||
Good for: Development, beta testing, first users
|
||
|
||
---
|
||
Small Scale — ~$20/mo (100 users)
|
||
|
||
What you get (on top of minimum):
|
||
- Neon Launch x2 ($5 each) — real production databases, auto-scaling compute, more storage
|
||
- AWS S3 for media uploads (10 GB) — proper file storage, not VPS disk
|
||
- Everything else still on free tiers
|
||
|
||
Limits:
|
||
- S3 egress: first 100 GB/mo free
|
||
- 3K emails/mo still (upgrade to Resend Pro at $20/mo if needed)
|
||
- Single VPS (no redundancy)
|
||
|
||
Good for: Soft launch, early adopters, getting first paying subscribers
|
||
|
||
---
|
||
Growth — ~$163/mo (1,000 users)
|
||
|
||
What you get (on top of small):
|
||
- Bigger VPS (8 vCPU, 16 GB RAM) — handles concurrent WebSocket connections, video processing
|
||
- Neon Scale x2 — higher connection limits, read replicas, compliance features
|
||
- Vercel Pro — commercial use allowed, 1 TB bandwidth, team collaboration
|
||
- Clerk Pro — SSO, enterprise auth features, unlimited orgs
|
||
- Resend Pro — 50K emails/mo
|
||
- Sentry Team — 100K errors/mo, multiple users, performance monitoring
|
||
- Upstash paid — more Redis capacity for rate limiting, sessions, caching
|
||
- AWS S3 100 GB + egress
|
||
|
||
Limits:
|
||
- Single VPS still (for HA, add second VPS +$18/mo)
|
||
- No dedicated DB (Neon Scale is still serverless)
|
||
|
||
Good for: Active community, real revenue, hundreds of daily active users
|
||
|
||
---
|
||
Break-even math
|
||
|
||
With $9/mo minimum infra and $18.80 net per subscriber:
|
||
|
||
┌─────────────────────────────┬────────────────────┐
|
||
│ │ Subscribers needed │
|
||
├─────────────────────────────┼────────────────────┤
|
||
│ Cover minimum infra ($9/mo) │ 1 subscriber │
|
||
├─────────────────────────────┼────────────────────┤
|
||
│ Cover small scale ($20/mo) │ 2 subscribers │
|
||
├─────────────────────────────┼────────────────────┤
|
||
│ Cover growth ($163/mo) │ 9 subscribers │
|
||
└─────────────────────────────┴────────────────────┘
|
||
|
||
┌─────────────────┬───────────────────────────────┬────────┐
|
||
│ Product │ Check │ Result │
|
||
├─────────────────┼───────────────────────────────┼────────┤
|
||
│ AITM CLI │ Build (tsc) │ PASS │
|
||
├─────────────────┼───────────────────────────────┼────────┤
|
||
│ AITM CLI │ Tests (520/520) │ PASS │
|
||
├─────────────────┼───────────────────────────────┼────────┤
|
||
│ AITM CLI │ Runtime (--version → 2.0.0) │ PASS │
|
||
├─────────────────┼───────────────────────────────┼────────┤
|
||
│ AITM CLI │ Help (23 commands listed) │ PASS │
|
||
├─────────────────┼───────────────────────────────┼────────┤
|
||
│ AITM MCP │ Build (tsc) │ PASS │
|
||
├─────────────────┼───────────────────────────────┼────────┤
|
||
│ AITM MCP │ Runtime (stdio server starts) │ PASS │
|
||
├─────────────────┼───────────────────────────────┼────────┤
|
||
│ AITM API Server │ Type-check │ PASS │
|
||
├─────────────────┼───────────────────────────────┼────────┤
|
||
│ AITM API Server │ Tests (538/538, +19 skip) │ PASS │
|
||
├─────────────────┼───────────────────────────────┼────────┤
|
||
│ AITM VS Code │ Tests (62/62) │ PASS │
|
||
├─────────────────┼───────────────────────────────┼────────┤
|
||
│ AITM Website │ Next.js build │ PASS │
|
||
├─────────────────┼───────────────────────────────┼────────┤
|
||
│ Gitgram Backend │ Type-check (0 errors) │ PASS │
|
||
├─────────────────┼───────────────────────────────┼────────┤
|
||
│ Gitgram Web │ Next.js build │ PASS │
|
||
├─────────────────┼───────────────────────────────┼────────┤
|
||
│ Gitgram Web │ Tests (72/72) │ PASS │
|
||
└─────────────────┴───────────────────────────────┴────────┘
|
||
|
||
we can fork bd https://github.com/upstash/context7.git https://github.com/BeehiveInnovations/pal-mcp-server.git for aitm mcp and aitm stuff and for
|
||
gitgram we can clone some openourse social media stuff becuase gitgram is social media layer for github repositories we can fork bd https://github.com/upstash/context7.git https://github.com/BeehiveInnovations/pal-mcp-server.git for aitm mcp and aitm stuff and for
|
||
gitgram we can clone some openourse social media stuff becuase gitgram is social media layer for github repositories vvv
|
||
---
|
||
Repos to Fork/Clone
|
||
|
||
For AITM MCP
|
||
|
||
┌───────────────────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
|
||
│ Repo │ What to Adapt │
|
||
├───────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ upstash/context7 │ Streamable HTTP transport (AITM is stdio-only), AsyncLocalStorage per-request context, tool description │
|
||
│ │ engineering, multi-agent setup CLI (aitm setup --claude --cursor), SDK client pattern with retry │
|
||
├───────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ BeehiveInnovations/pal-mcp-server │ ToolAnnotations (readOnlyHint/destructiveHint) for all 40 tools, modular tool class architecture (extract from │
|
||
│ │ monolithic index.ts), DISABLED_TOOLS env var, standardized output envelope, path validation for restore safety │
|
||
├───────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ abhigyanpatwari/GitNexus │ Zero-server knowledge graph + Graph RAG agent over repos. Adapt for AITM code-context indexing, checkpoint │
|
||
│ → external/gitnexus │ knowledge graphs, and Gitgram repo explore/visualisation surface. Cloned 2026-06-21. │
|
||
├───────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ gastownhall/beads │ Git-native DAG issue tracker for AI agents. `bd ready` shows dependency-unblocked work with hash-based IDs. │
|
||
│ → external/beads │ Reference for AITM task/issue tracking integration and multi-agent coordination. Cloned 2026-06-21. │
|
||
└───────────────────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
|
||
|
||
For Gitgram (Social Layer)
|
||
|
||
┌─────┬──────────────────────────────────┬───────┬─────────┬───────────────────────────────────────────────────────────────────────────────────────────┐
|
||
│ # │ Repo │ Stars │ License │ Why │
|
||
├─────┼──────────────────────────────────┼───────┼─────────┼───────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ 1 │ codinginflow/nextjs-15-social- │ 417 │ -- │ Exact same stack (Next.js + Prisma + PG). Prisma schema maps 1:1 to Gitgram. Infinite │
|
||
│ │ media-app → external/nextjs-15- │ │ │ scroll, optimistic updates, notifications. Cloned 2026-06-21. │
|
||
│ │ social-media-app │ │ │ │
|
||
├─────┼──────────────────────────────────┼───────┼─────────┼───────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ 2 │ leandronorcio/munia │ 293 │ MIT │ Most complete features: GitHub OAuth, @mentions, hashtags, nested comments, drag-drop │
|
||
│ │ → external/munia │ │ │ media, S3 uploads, accessibility. Cloned 2026-06-21. │
|
||
├─────┼──────────────────────────────────┼───────┼─────────┼───────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ 3 │ TomDoesTech/t3-twitter-clone │ 189 │ MIT │ Only one with Express branch — matches Gitgram's Express backend. Type-safe tRPC │
|
||
│ │ → external/t3-twitter-clone │ │ │ patterns. Cloned 2026-06-21. │
|
||
├─────┼──────────────────────────────────┼───────┼─────────┼───────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ 4 │ karanpratapsingh/Proximity │ 360 │ GPL-3 │ Best React Native social app with Prisma. Real-time messaging via GraphQL subscriptions. │
|
||
│ │ → external/proximity │ │ │ Reference only (GPL). Cloned 2026-06-21. │
|
||
├─────┼──────────────────────────────────┼───────┼─────────┼───────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ 5 │ bluesky-social/social-app │ 17.8K │ MIT │ Production-scale feed algorithms, notifications, moderation. Architecture reference. │
|
||
│ │ → external/bluesky-social-app │ │ │ Cloned 2026-06-21. │
|
||
├─────┼──────────────────────────────────┼───────┼─────────┼───────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ 6 │ abhigyanpatwari/GitNexus │ -- │ -- │ Client-side knowledge graph + Graph RAG over any repo. Reference for Gitgram repo │
|
||
│ │ → external/gitnexus │ │ │ explore/visualisation. Also useful for AITM. Cloned 2026-06-21. │
|
||
└─────┴──────────────────────────────────┴───────┴─────────┴───────────────────────────────────────────────────────────────────────────────────────────┘
|
||
|
||
Quick-win bonus
|
||
|
||
- amirfakhrullah/gh-social (MIT) — The only "GitHub Social Platform" found. Syncs GitHub follows/stars to a social feed. Next.js + tRPC + Clerk +
|
||
Drizzle + Neon. Closest concept to Gitgram. Cloned 2026-06-21 → external/gh-social.
|
||
- gastownhall/beads (MIT) — Git-native DAG issue tracker by Steve Yegge for AI agents. Cloned 2026-06-21 → external/beads.
|
||
|
||
---
|
||
Top Actionable Items from Research
|
||
|
||
AITM MCP (high priority, small effort):
|
||
1. Add ToolAnnotations to all 40 tools — readOnlyHint: true for read tools, destructiveHint: true for restore
|
||
2. Add Streamable HTTP transport (from context7 pattern) — enables web/VS Code clients
|
||
3. Extract tools from monolithic index.ts into modular files
|
||
|
||
Gitgram (reference patterns to study):
|
||
1. Prisma schema design from nextjs-15-social-media-app
|
||
2. @mentions + hashtag system from munia
|
||
3. Feed pagination (cursor-based infinite scroll) from both
|
||
4. GitHub API integration from gh-social
|
||
|
||
│ BloopAI/vibe-kanban │ 24.6k │ Kanban for AI agents, MCP server+client, git worktree isolation, diff review. Best task board │
|
||
│ │ │ foundation. │
|
||
├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
|
||
│ gastownhall/beads (bd!) │ 20.4k │ Git-native DAG issue tracker made for AI agents. This is what bd is. │
|
||
├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
|
||
│ a2aproject/a2a-js │ 509 │ Official A2A TypeScript SDK. Needed for standards compliance. │
|
||
├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
|
||
│ agentgateway/agentgateway │ 2.3k │ Rust proxy for A2A + MCP traffic. Security/observability built in. │
|
||
|
||
├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ GongRzhe/A2A-MCP-Server │ 147 │ Bridges MCP ↔ A2A so Claude can talk to A2A agents. │
|
||
|
||
├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
|
||
│ Open-ACP/OpenACP │ 58 │ Connects 28+ AI agents to Telegram, Discord, Slack. Real-time messaging. │
|
||
└───────────────────────────┴───────┴───────────────────────────────────────────────────────────────────────────────────────────────────┘
|
||
|
||
|
||
Key insight about bd (Beads)
|
||
|
||
|
||
Beads by Steve Yegge is exactly what you're already using for task tracking! It's a git-native graph issue tracker designed for AI agents.
|
||
|
||
bd ready shows unblocked work, dependency DAGs, hash-based IDs for concurrent agents. 20k+ stars, MIT.
|
||
|
||
│ BloopAI/vibe-kanban │ 24.6k │ Kanban for AI agents, MCP server+client, git worktree isolation, diff review. Best task board │
|
||
│ │ │ foundation. │
|
||
├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
|
||
│ gastownhall/beads (bd!) │ 20.4k │ Git-native DAG issue tracker made for AI agents. This is what bd is. │
|
||
├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
|
||
│ a2aproject/a2a-js │ 509 │ Official A2A TypeScript SDK. Needed for standards compliance. │
|
||
├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
|
||
│ agentgateway/agentgateway │ 2.3k │ Rust proxy for A2A + MCP traffic. Security/observability built in. │
|
||
|
||
├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
│ GongRzhe/A2A-MCP-Server │ 147 │ Bridges MCP ↔ A2A so Claude can talk to A2A agents. │
|
||
|
||
├───────────────────────────┼───────┼───────────────────────────────────────────────────────────────────────────────────────────────────┤
|
||
|
||
│ Open-ACP/OpenACP │ 58 │ Connects 28+ AI agents to Telegram, Discord, Slack. Real-time messaging. │
|
||
└───────────────────────────┴───────┴───────────────────────────────────────────────────────────────────────────────────────────────────┘
|
||
|
||
|
||
Key insight about bd (Beads)
|
||
|
||
|
||
Beads by Steve Yegge is exactly what you're already using for task tracking! It's a git-native graph issue tracker designed for AI agents.
|
||
|
||
bd ready shows unblocked work, dependency DAGs, hash-based IDs for concurrent agents. 20k+ stars, MIT.
|
||
|
||
# Unified Manual Launch Plan for Gitgram + AITM
|
||
|
||
## Summary
|
||
|
||
Prepare both products for a parallel launch using a single server / operator-managed deployment model as the source of truth. The plan should treat the
|
||
existing repo as mostly implementation-complete, but should not trust the docs blindly: first reconcile deployment artifacts, environment contracts, and
|
||
stale references, then execute a manual launch path that does not depend on unfinished CI/CD automation.
|
||
|
||
Success means:
|
||
|
||
- AITM npm packages are published and installable.
|
||
- Gitgram backend/web and AITM API are deployable from documented manual commands.
|
||
- Production secrets/env contracts are complete and validated.
|
||
- Health checks, rollback steps, and operator runbooks match the actual repo layout.
|
||
- Stale or conflicting deployment guidance is removed or explicitly deprecated.
|
||
|
||
## Implementation Changes
|
||
|
||
### 1. Establish one canonical launch topology
|
||
|
||
- Make the manual-ops path the primary launch contract: single operator-managed host, Docker/PM2/systemd as applicable, no dependency on unfinished
|
||
GitHub Actions deployment flows.
|
||
- Standardize the production target as:
|
||
- Gitgram backend: long-running Node service on the server.
|
||
- Gitgram web: long-running Next.js service on the server.
|
||
- AITM API: long-running Node service on the server.
|
||
- Shared infra: PostgreSQL + Redis on the same host or tightly coupled managed services, but documented as one operational unit.
|
||
- Demote GitHub Actions deploy workflows to “future automation” unless they fully match the manual launch path.
|
||
|
||
### 2. Reconcile repo truth with docs before launch execution
|
||
|
||
- Audit and fix contradictions between SINGLE_SOURCE_PLAN.md, docs/deploy-pipeline.md, docs/ops-quickref.md, docs/runbook.md, compose files, and actual
|
||
workflow filenames.
|
||
- Remove or clearly mark stale deployment variants that conflict with the chosen topology.
|
||
- Resolve broken references in docs, especially any paths/services that do not exist in the tree.
|
||
- Normalize naming so the same service names, ports, health endpoints, workflow names, and env var conventions are used everywhere.
|
||
- Treat docs/can be fork.md as the maintained reference-clone inventory; use SINGLE_SOURCE_PLAN.md as the canonical execution plan for launch sequencing.
|
||
|
||
### 3. Lock the manual launch path per product
|
||
|
||
- AITM:
|
||
- Verify package publish order and prerequisites for @gitgram/timemachine and @gitgram/timemachine-mcp.
|
||
- Define the exact manual publish checklist, post-publish verification, and rollback/version bump procedure.
|
||
- Define the exact API deployment procedure, including build, env validation, migration application, service restart, and health verification.
|
||
- Gitgram:
|
||
- Define the exact backend deployment procedure, including Prisma generation/migration, build, restart, and health verification.
|
||
- Define the exact web deployment procedure, including build, runtime env injection, restart, and smoke verification.
|
||
- Shared:
|
||
- Choose one restart/control mechanism per service and document it as canonical. If both PM2 and systemd are kept, assign one as primary and one as
|
||
fallback, not equal-status alternatives.
|
||
|
||
### 4. Harden secrets and env contracts for launch
|
||
|
||
- Use docs/secrets-contract.md and docs/environment-matrix.md as the starting point, but reconcile them with actual runtime/package needs.
|
||
- Produce one canonical required-vars list for:
|
||
- Gitgram backend
|
||
- Gitgram web
|
||
- AITM API
|
||
- AITM package publish/release flow
|
||
- Validate that production-only integrations needed for launch are present and named consistently, especially database, Redis, JWT, Polar, S3/storage,
|
||
email, and any internal auth secrets.
|
||
- Ensure validation scripts and runbooks match the chosen unprefixed/prefixed env convention and the manual deployment path.
|
||
- Explicitly document which secrets are required before first launch vs optional post-launch integrations.
|
||
|
||
### 5. Define launch-day operations and rollback
|
||
|
||
- Convert the runbook into an operator-focused launch sequence with:
|
||
- preflight checks
|
||
- ordered deploy steps
|
||
- health gates
|
||
- smoke checks
|
||
- rollback commands
|
||
- post-launch monitoring window
|
||
- Rollback should be manual-first and concrete:
|
||
- previous package version for npm artifacts
|
||
- previous app build/image/tag for server services
|
||
- DB migration rollback policy or “restore from backup only” policy where down-migrations are not supported
|
||
- Require a backup/checkpoint step before applying production migrations.
|
||
|
||
## Public Interfaces / Contracts
|
||
|
||
- No product API redesign is planned.
|
||
- Public-facing contract changes are limited to:
|
||
- canonical deployment/runbook docs
|
||
- explicit deprecation of stale deployment paths and references
|
||
- If any current docs mention missing components such as non-existent service paths, update the documentation contract rather than inventing new
|
||
components for launch.
|
||
|
||
## Test Plan
|
||
|
||
- Verify repo-level build/test/typecheck commands for the launch-critical services still pass.
|
||
- Dry-run the manual deployment commands in a staging-like environment for:
|
||
- Gitgram backend
|
||
- Gitgram web
|
||
- AITM API
|
||
- AITM package publish verification flow
|
||
- Validate health endpoints after each service restart.
|
||
- Run minimal smoke scenarios:
|
||
- Gitgram auth and basic API reachability
|
||
- Gitgram web load and API connectivity
|
||
- AITM API health/readiness and one representative core flow
|
||
- npm install plus basic CLI/MCP invocation for published AITM packages
|
||
- Test rollback instructions at least once in staging-like conditions.
|
||
|
||
## Assumptions and Defaults
|
||
|
||
- Launch is for both products in parallel, not a staggered product strategy.
|
||
- The delivery path is manual operations first, with CI/CD treated as non-blocking unless brought into alignment.
|
||
- The hosting model is single server / operator-managed, not a multi-platform redesign.
|
||
- Existing code is assumed largely complete; the main launch risk is operational inconsistency, stale docs, and deployment drift.
|
||
- Any workflow or doc that conflicts with the chosen manual launch path should be updated, deprecated, or ignored rather than preserved for symmetry.
|