How maharshi0143/algoryn works
1. What this repository is
- This is a single backend service for “DevTrack AI,” a developer analytics platform.
- It exposes an Express API, connects to PostgreSQL, polls external coding platforms, generates AI-driven reports/insights, and pushes realtime notifications via Socket.IO.
2. Top-level runtime and startup boundary
- The entrypoint is src/server.js.
- Startup sequence is: load env → wait for PostgreSQL → initialize cron jobs → create HTTP server → attach Socket.IO → listen on port → register graceful shutdown.
- Shutdown stops cron tasks, closes Socket.IO, and ends the DB pool, so background work is part of the same process boundary as the API.
3. Request path inside the API
- Requests flow through src/app.js middleware first: security headers, CORS, JSON/urlencoded parsing, compression, logging, cookies, and global rate limiting.
- Route handlers then apply route-specific auth, validation, and tighter rate limits before reaching controllers.
- Controllers are thin: they read request inputs, call services, and return a standard JSON envelope.
4. Layered application structure
- The code is organized into clear layers: routes → controllers → services → repositories.
- Services contain the business rules and orchestration.
- Repositories are the data-access boundary and are the only layer that talks to PostgreSQL.
- This makes the diagram easy to draw as a strict vertical flow with external integrations hanging off the service layer.
5. Database and persistence
- PostgreSQL is the primary system of record.
- The schema includes users, refresh tokens, coding profiles, problem stats, GitHub stats, daily stats, contest history, achievements, notifications, goals, friends, activity logs, email preferences, contest reminders, and weekly reports.
- Most repositories use raw pg queries; only analytics and leaderboard use Knex, so the data-access boundary is mixed but still centralized.
- All user-owned data cascades on user deletion.
6. Authentication and session model
- Auth is JWT-based with short-lived access tokens and longer-lived refresh tokens.
- Refresh tokens are stored hashed in PostgreSQL and also issued as httpOnly cookies.
- authMiddleware verifies Bearer access tokens, loads the user from the database, and blocks inactive accounts.
- This is a stateless API externally, but session revocation is backed by the refresh_tokens table.
7. Core product domain
- The main domain revolves around coding profiles per platform, then syncing platform stats into normalized tables.
- Supported platforms are GitHub, LeetCode, Codeforces, CodeChef, GFG, and HackerRank.
- Dashboard, analytics, leaderboard, achievements, goals, friends, public profile, and export features all read from the same shared profile/stats model rather than duplicating data.
8. External integration layer
- External platform adapters live in src/integrations/*.
- Each platform has its own service file that knows how to call that platform’s API and normalize its response.
- GitHub is the most complex integration because it uses both REST and GraphQL, including optional token-based contribution data.
- Groq is the AI integration used for insights and reports.
9. Background jobs and scheduled synchronization
- The app runs nine cron jobs from src/jobs.
- Five jobs sync platform data every six hours; others generate achievements, daily snapshots, weekly reports, and contest reminders.
- Jobs are wrapped in an in-memory lock so overlapping runs are skipped.
- This means the platform is not only request-driven; it also has a significant scheduled processing subsystem.
10. Realtime notifications
- Socket.IO is initialized on the same Node server and authenticated with JWT during the handshake.
- Users join a room for their own user ID only.
- Notification creation writes to the database first, then emits notification:new to the user’s room.
- Realtime delivery is therefore an async side effect of persisted notification records, not the source of truth.
11. AI, reports, and exports
- AI features build prompts from current user stats and send them to Groq.
- Weekly reports combine stats, achievements, goals, and recent activity, then store the generated summary in PostgreSQL.
- Export endpoints read from multiple repositories and produce JSON, PDF, or PNG representations.
- These are read-heavy orchestration features rather than separate services.
12. Security, validation, and reliability boundaries
- Security and control points include Helmet, CORS, rate limiting, validation, bcrypt password hashing, and refresh-token rotation.
- Validation is handled by express-validator rules plus a shared validation middleware.
- Logging goes through Winston, request logs are piped through Morgan, and Sentry captures unhandled errors and performance traces in production.
- Health checks include database connectivity, so the API can report partial or full outage conditions.
13. Operational shape of the system
- The app expects a single frontend origin and a single PostgreSQL database.
- Redis appears only in Docker Compose and is not wired into the application code, so it is not part of the runtime architecture.
- The service can be deployed as a standalone Node process behind a platform like Render or Railway, with cron jobs running inside that same process.
14. How to draw the main data flows
- User request flow: client → Express middleware → route/controller → service → repository → PostgreSQL → response.
- Sync flow: cron job or manual sync endpoint → integration client → service normalization → repository updates → PostgreSQL → notification side effect.
- AI/report flow: service reads internal stats from PostgreSQL → Groq API call → parsed result → database/email/export output.
- Realtime flow: database write for notification → Socket.IO emit to user room.
Main entry points: repositories Repositories · jobs Cron Jobs · app.js Express App · server.js Server
Components 18
Runtime
Single Node process boundary for API, jobs, and realtime
API Layer
Express request pipeline and route handling
- Express App · Middleware stack and route mounting
server/src/app.js - Middleware · Security, parsing, logging, auth, validation, and rate limits
server/src/middlewares - Routes · HTTP endpoints grouped by feature
server/src/routes - Controllers · Thin request handlers that call services
server/src/controllers
Domain
Core business services and orchestration
- Services · Core orchestration and domain rules
server/src/services - Sync Service · Coordinates platform polling and normalization
server/src/services/syncService.js - AI Service · Builds prompts and calls Groq for insights
server/src/services/aiService.js - Report Service · Generates weekly summaries from stored stats
server/src/services/weeklyReportService.js - Export Service · Assembles JSON, PDF, and PNG exports
server/src/services/exportService.js - Notifications · Persists and emits realtime user notifications
server/src/services/notificationService.js - Auth · JWT access, refresh-token rotation, bcrypt, and account checks
server/src/services/authService.js
Data
Persistence boundary and database access
- Repositories · PostgreSQL boundary for users, stats, tokens, and reports
server/src/repositories - PostgreSQL · Primary system of record
server/database/schema.sql
Integrations
External platform and AI adapters
- Platform APIs · GitHub, LeetCode, Codeforces, CodeChef, GFG, HackerRank, Groq
server/src/integrations
Background
Scheduled synchronization and reporting jobs
- Cron Jobs · In-process scheduled sync, snapshots, reminders, and reports
server/src/jobs
Connections 21
- Client → Express App: HTTP requests · API traffic enters the Express app
- Server → Express App: mounts · Bootstrap creates and configures the app
- Server → Cron Jobs: starts · Scheduled tasks begin in the same process
- Server → Socket.IO: attaches · Realtime server is attached to the HTTP server
- Express App → Middleware: uses · Shared middleware runs before routes
- Express App → Routes: mounts · Feature routes are registered on the app
- Routes → Controllers: dispatches · Routes hand requests to controllers
- Controllers → Services: calls · Controllers delegate business work to services
- Services → Repositories: reads/writes · Services use repositories for persistence
- Repositories → PostgreSQL: queries · Repositories are the only database access layer
- Auth → Repositories: loads users · Auth middleware and service depend on token and user storage
- Sync Service → Platform APIs: polls · Platform adapters fetch and normalize remote stats
- Sync Service → Repositories: updates · Normalized stats are stored after sync
- Cron Jobs → Sync Service: runs · Cron sync jobs invoke the sync pipeline
- Cron Jobs → Report Service: generates · Weekly report job builds persisted summaries
- Cron Jobs → Notifications: reminds · Reminder and achievement jobs create notifications
- AI Service → Platform APIs: calls Groq · AI prompts are sent to the Groq service
- Report Service → Repositories: reads stats · Reports combine stored stats, goals, and activity
- Export Service → Repositories: reads data · Exports aggregate multiple data sources
- Notifications → Socket.IO: emits · Persisted notifications are pushed to user rooms
- Notifications → Repositories: persists · Notification records are stored before delivery