Currently Working On
CommitR
Commitr is a social platform built for developers to share their work, ideas, and progress — directly from their code. It blends the collaborative spirit of GitHub with the expressiveness of social media, creating a new way for developers to showcase commits, repositories, and insights as interactive posts. On Commitr, developers can: Connect their GitHub to automatically pull repositories and commits. Create custom posts combining text, markdown, and embedded GitHub data — like repos, commits, and file snippets. Engage with others through likes, comments, and follows, forming a vibrant developer feed. Showcase projects and technical stories as part of their public profile. Commitr focuses on bridging the gap between coding and communication — turning commits into conversations and repositories into reputation.
Next.jsNest.jsPostgreSQLMongoDB....Other Later
Frontend Documentation — DevSocial (GitHub-first Custom Posts)
Overview
This document describes the frontend architecture, user flows, UX design, API interactions, and deployment considerations for the developer social platform “DevSocial.”
The app enables developers to create custom posts that embed GitHub repositories, commits, and file snippets.
There is no LinkedIn integration — all professional context can be manually included via posts.
Core Objectives
- Allow users to authenticate via GitHub.
- Enable creation of rich, markdown-based posts containing text and GitHub embeds.
- Provide a clean, responsive UI for browsing feeds, profiles, and posts.
- Securely interact with backend APIs for post management and GitHub data retrieval.
- Ensure good performance, accessibility, and security from the client side.
User Journeys
1. Authentication and Onboarding
- The user signs in using GitHub OAuth.
- The app retrieves a session token from the backend.
- The user completes onboarding by adding basic profile information such as display name and bio.
2. Creating Custom Posts
- User accesses the Post Composer screen.
- They can write content in markdown or plain text.
- They can search and select repositories, commits, or file snippets from their linked GitHub account.
- The post preview shows embedded GitHub items.
- Upon submission, the frontend sends the post payload (markdown + embed references) to the backend.
3. Viewing and Interacting with Posts
- Feed view displays posts with embedded repo/commit cards.
- Embedded data comes from backend snapshots of GitHub content.
- Users can like, comment, and share posts.
- Comments appear in threaded format below the post.
4. Managing Account
- Users can view or edit profile info (avatar, bio, skills, location).
- They can manage their GitHub connection (connect/disconnect).
- Disconnection revokes access and hides embedded GitHub features.
Core UI Components
| Component | Description |
|---|---|
| Auth Views | Login, logout, and session-aware route protection. |
| Feed | Displays list of posts with pagination and interaction buttons. |
| Post Composer | Markdown editor for creating posts, with repo and commit attachment UI. |
| Repo Selector | UI for searching and selecting GitHub repositories. |
| Commit Selector | Lists commits of a selected repository with date, author, and message. |
| Embed Renderer | Displays repo cards, commit summaries, and file snippets. |
| Profile Page | Shows user details, pinned posts, and GitHub stats summary. |
| Settings Page | Manage account info, GitHub connection, and notification preferences. |
Page Structure and Navigation
| Page | Purpose |
|---|---|
/ | Main feed showing posts from all users or followed users. |
/compose | New post creation interface. |
/profile/:username | Public profile showing user posts and stats. |
/post/:id | Single post view with comments and embeds. |
/settings | Manage account and linked GitHub. |
API Interactions (Frontend Perspective)
| Endpoint | Method | Purpose |
|---|---|---|
/api/session | GET | Get current session and linked GitHub account. |
/api/github/repos | GET | List user's repositories (proxied via backend). |
/api/github/repos/:owner/:repo/commits | GET | List commits for a repository. |
/api/github/repos/:owner/:repo/commits/:sha | GET | Retrieve details and file list for a specific commit. |
/api/github/repos/:owner/:repo/contents/:path?ref=sha | GET | Fetch file content for snippet preview. |
/api/posts | POST | Create new post with text and embed references. |
/api/posts | GET | Get list of posts for feed. |
/api/posts/:id | GET | Fetch single post details. |
/api/posts/:id/like | POST | Like or unlike a post. |
/api/posts/:id/comments | POST | Add a comment to a post. |
All API calls are authenticated and should be made with session credentials.
Frontend must never send GitHub access tokens directly to GitHub — all calls are proxied via the backend.
UX Guidelines
- Post Creation: Allow live markdown preview; clearly label attached GitHub content.
- Embeds: Show repo name, description, stars, and commit metadata. Include optional snippet previews.
- Accessibility: Ensure all buttons are keyboard-navigable and color contrast meets WCAG 2.1 standards.
- Errors: Display friendly messages for rate-limit errors or expired GitHub connections.
- Performance: Cache repo lists temporarily to minimize redundant backend requests.
Data Caching & State Management
- Use client-side caching (e.g., React Query or SWR pattern) for posts, repos, and commits.
- Use background revalidation for feed updates.
- Cache authenticated user’s repo list for a short duration (e.g., 5 minutes) to minimize GitHub API usage.
Security and Privacy
- No access tokens stored or visible in the client.
- Use secure HTTPS-only requests.
- Sanitize all markdown content before rendering.
- Respect user privacy settings for embedded GitHub data.
Accessibility Checklist
- Keyboard focus visible for all interactive elements.
- All images and avatars include descriptive alt text.
- ARIA labels on non-text controls.
- Color contrast ratio at least 4.5:1 for text.
Localization
- Support future internationalization by externalizing strings.
- Use consistent date/time formatting in local timezone.
Analytics (Optional)
Track non-sensitive metrics like:
- Post creation count
- Repo/commit attachment frequency
- User session length Avoid sending any code content or commit diffs to analytics.
Deployment
- Deploy frontend via a modern hosting platform with built-in CI/CD.
- Store environment variables securely.
- Ensure CORS configuration allows requests only to your backend domain.
Future Enhancements
- Live sync mode for GitHub repos (auto-refresh stars, commits).
- Enhanced diff viewer for commits.
- Post tagging and topic discovery.
- Dark mode and customizable syntax highlighting.
Backend Documentation — DevSocial (GitHub-first Custom Posts)
Overview
This document defines the backend architecture, API design, data model, and operational requirements for the DevSocial platform.
The backend manages user authentication, GitHub integration, post storage, and snapshotting of GitHub content embedded in posts.
Objectives
- Provide secure GitHub OAuth authentication.
- Proxy GitHub API requests to protect tokens.
- Create and store posts containing references to GitHub repos and commits.
- Snapshot GitHub content to ensure posts remain viewable even if upstream data changes.
- Serve feed and profile data efficiently with pagination and caching.
- Enforce rate limits, data size limits, and security best practices.
Core Responsibilities
| Area | Description |
|---|---|
| Authentication | Handle GitHub OAuth flow and user session management. |
| GitHub Proxy | Securely fetch repo and commit data using stored tokens. |
| Posts API | Accept and store posts with embedded GitHub metadata. |
| Snapshotting | Capture and cache GitHub repo/commit data for post stability. |
| Feeds | Serve paginated posts for feed and profiles. |
| Storage | Manage user, post, and embed data in a relational database. |
Data Model Overview
Users
- Unique ID, display name, email, avatar URL
- Account creation and last login timestamps
GitHub Accounts
- User reference
- GitHub login ID, OAuth tokens, scopes, expiry
- Encrypted storage for access tokens
- Last synchronization date
Posts
- Post ID, author ID
- Text content (markdown)
- Created/updated timestamps
Embeds
- Embed ID, post reference
- Type (repo or commit)
- Provider (
github) - Provider reference (owner, repo, sha, file list)
- Snapshot metadata (cached GitHub JSON)
- Display metadata (repo/commit summary fields)
- Status (
pending,complete,failed)
Embed Files (optional)
- Embed reference
- File path, content snippet, language metadata
API Endpoints Summary
| Endpoint | Method | Description |
|---|---|---|
/api/oauth/github/login | GET | Redirects user to GitHub OAuth authorization URL. |
/api/oauth/github/callback | GET | Handles GitHub OAuth callback and stores access token. |
/api/github/repos | GET | Lists authenticated user’s repositories. |
/api/github/repos/:owner/:repo/commits | GET | Returns commits for selected repo. |
/api/github/repos/:owner/:repo/commits/:sha | GET | Returns detailed commit info (message, author, files). |
/api/github/repos/:owner/:repo/contents/:path?ref=sha | GET | Fetches file contents for snippets. |
/api/posts | POST | Creates new post, triggers GitHub snapshotting. |
/api/posts | GET | Retrieves paginated posts (feed). |
/api/posts/:id | GET | Fetches single post with embeds. |
/api/posts/:id/like | POST | Like or unlike a post. |
/api/posts/:id/comments | POST | Add a comment to a post. |
Snapshot Workflow
- The frontend submits a post with text and embed references (repo and commit identifiers).
- Backend validates the session and permissions.
- Backend queries GitHub API for each referenced item:
- Repository metadata (description, stars, language)
- Commit metadata (message, author, date, changed files)
- File contents (if user selected snippets)
- Responses are stored as snapshots in the database.
- Post is saved and immediately visible in feed (with either pending or complete snapshot status).
- Optionally, background jobs revalidate snapshots later.
Rate Limiting & Caching
- Per-user rate limits for GitHub proxy requests.
- Cache frequently accessed GitHub data to minimize API usage.
- Apply TTL-based cache invalidation for repo and commit metadata.
- Track quota usage and prevent abuse.
Background Jobs
- Process heavy snapshot requests asynchronously.
- Re-sync GitHub data periodically or on user request.
- Retry failed snapshots automatically (with capped retries).
Security & Compliance
- Encrypt OAuth tokens at rest.
- Sanitize all markdown before saving or rendering.
- Use HTTPS for all API endpoints.
- Respect GitHub API rate limits and terms of service.
- Provide data deletion options when users disconnect GitHub.
- Implement audit logs for sensitive actions.
Operational Practices
- Monitor API latency and error rates.
- Log snapshot job status, queue depth, and failures.
- Provide admin endpoints for retrying failed snapshots.
- Set alerting for near-quota GitHub API usage.
Performance Recommendations
- Paginate feed and repository responses.
- Use efficient queries with indexes on user_id and created_at.
- Store trimmed file contents (not entire repositories).
- Compress and store JSON snapshots where possible.
Privacy Principles
- Store only data necessary for displaying posts.
- Do not retain entire GitHub repos or commit histories.
- Allow full account and data deletion at user request.
Future Backend Enhancements
- Scheduled snapshot re-syncs with user-configurable frequency.
- Support for “live” embeds that update automatically.
- Export functionality for user posts and embedded snapshots.
- Deduplication for identical snapshots to reduce storage.
Deployment
- Host backend together with frontend (e.g., Next.js fullstack) or as standalone API service.
- Use managed Postgres (like Supabase) for database.
- Securely store credentials and API keys as environment variables.
Testing & QA
- Unit tests for snapshot logic and API validation.
- Integration tests for OAuth and GitHub proxy flows.
- End-to-end tests for post creation and rendering pipeline.
Summary
The backend acts as the trusted intermediary between the frontend and GitHub.
It ensures secure token handling, durable snapshots, and consistent data delivery for posts embedding real GitHub activity.
The architecture is modular, scalable, and built to support future expansion such as background workers, notifications, and extended social features.