Complete file index

Every .ts file under hono-backend/src (except tests).

`(root)/`

File	What it does (short)
`index.ts`	Think of this file as the reception desk of hono-backend.

`config/`

File	What it does (short)
`db.ts`	MongoDB is the database where all persistent data lives (users, questions,
`env.ts`	Environment configuration (loaded once at process start)
`permissions.ts`	Admin permissions (central registry)

`constants/`

File	What it does (short)
`practice-catalog-kind.ts`	Practice catalog kind (per subject)
`practice-pyq-exam-category.ts`	Practice PYQ exam category (learner-facing bucket)

`lib/`

File	What it does (short)
`format-zod-issue-path.ts`	Format Zod validation paths for API error messages
`json-parse-location.ts`	JSON parse error locations (line / column)

`middleware/`

File	What it does (short)
`admin.middleware.ts`	Two layers of admin security (used together on /api/v1/admin/*):
`auth.middleware.ts`	This runs before protected route handlers. It answers one question:
`internal-key.middleware.ts`	Some endpoints must NOT use Google login — they are called by our own

`models/`

File	What it does (short)
`content.model.ts`	Simple CMS-style pages: announcements and exam-info articles shown in
`crowd-video-timestamp.model.ts`	Community-submitted time markers on videos (“there’s a question here”)
`device-token.model.ts`	Stores Firebase Cloud Messaging (FCM) tokens per user device so push
`localized-text.schema.ts`	A reusable embedded sub-schema for text that can appear in English (`en`)
`marketing-deal.model.ts`	A commercial deal with a sponsor: amounts, status, and optional **coupon
`marketing-sponsor.model.ts`	CRM record for a sponsor (YouTuber/creator) we run marketing deals with.
`mock-test.model.ts`	Timed mock exams built from existing `Question` documents, with per-
`notification-daily-rollup.model.ts`	Pre-aggregated daily metrics for push notifications (sent, opened, by
`notification-log.model.ts`	Audit log of every push notification we attempt: template, variables,
`notification-preference.model.ts`	Per-user push notification settings in India Standard Time (IST): when
`playlist.model.ts`	Curated playlists of catalog videos — usually admin-built study paths
`question.model.ts`	Multiple-choice questions tied to a moment in a YouTube video
`refresh-token.model.ts`	Stores long-lived refresh tokens so clients can get new access tokens without
`user-library-channel.model.ts`	Per-user subscribed/saved YouTube channels with cached channel metadata.
`user-library-video.model.ts`	Per-user saved videos in their library (bookmark list). Denormalized
`user-playlist.model.ts`	User-created playlists of YouTube videos (by `youtubeVideoId` strings),
`user.model.ts`	The Mongoose model for app users — people who sign in with Google and use
`video-timestamp.model.ts`	A marker on a video timeline (e.g. “question at 10:33”) — either added
`video.model.ts`	Canonical catalog of YouTube videos the product knows about — metadata

`models/current-affairs/`

File	What it does (short)
`current-affair-flashcard.model.ts`	MONGODB: `currentaffairflashcards` \| SRS via UserRevisionItem (flashcard)
`current-affair-item.model.ts`	MONGODB: `currentaffairitems` \| dailyIssueId → DailyIssue
`current-affair-mcq.model.ts`	MONGODB: `currentaffairmcqs` \| SRS via UserRevisionItem (contentType mcq)
`current-affair-related-pyq.model.ts`	MONGODB: `currentaffairrelatedpyqs`
`daily-issue.model.ts`	MONGODB: `dailyissues` \| Unique `date` (YYYY-MM-DD)
`nexus-entity.model.ts`	MONGODB: `nexusentities` \| Referenced from CurrentAffairItem.entities
`user-ca-news-bookmark.model.ts`	MONGODB: `usercanewsbookmarks` \| Unique (userId, itemId)
`user-ca-news-revision.model.ts`	MONGODB: `usercanewsrevisions` \| itemId → CurrentAffairItem
`user-revision-item.model.ts`	MONGODB: `userrevisionitems` \| contentId → Mcq or Flashcard collections

`models/practice-pyq/`

File	What it does (short)
`practice-pyq-import-meta.schema.ts`	NOT a collection — merged into PracticePyqQuestion root for import fidelity.
`practice-pyq-question.model.ts`	MONGODB: `practicepyqquestions` \| subtopicId → PracticePyqSubtopic
`practice-pyq-subject.model.ts`	MONGODB: `practicepyqsubjects` \| Hierarchy: Subject → Topic → Subtopic → Question
`practice-pyq-subtopic.model.ts`	MONGODB: `practicepyqsubtopics` \| topicId → PracticePyqTopic; questions hang here
`practice-pyq-topic.model.ts`	MONGODB: `practicepyqtopics` \| subjectId → PracticePyqSubject (unique slug per subject)
`practice-pyq-user-question-card.model.ts`	MONGODB: `practicepyquserquestioncards` \| Unique (userId, questionId)

`models/user-study-stats/`

File	What it does (short)
`practice-attempt-event.model.ts`	MONGODB: `practiceattemptevents` \| One row per graded attempt (IST dayKey)
`user-practice-daily-rollup.model.ts`	MONGODB: `userpracticedailyrollups` \| Unique (userId, catalog, dayKey)
`user-practice-topic-rollup.model.ts`	MONGODB: `userpracticetopicrollups` \| Unique (userId, catalog, topicId)
`user-recent-practice-subtopic.model.ts`	MONGODB: `userrecentpracticesubtopics` \| Updated by record-recent-practice-subtopic.ts

`routes/`

File	What it does (short)
`admin.route.ts`	admin.route.ts — Staff / admin API (content, users, videos, nested catalogs)
`auth.route.ts`	auth.route.ts — Authentication & session tokens
`current-affairs-admin.routes.ts`	current-affairs-admin.routes.ts — Staff CRUD for daily CA issues & Nexus
`current-affairs-public.routes.ts`	current-affairs-public.routes.ts — Daily CA reader, revision, search (learners)
`marketing-admin.routes.ts`	marketing-admin.routes.ts — Sponsors & signup coupon deals
`notification.route.ts`	notification.route.ts — Push notifications (FCM), prefs, admin metrics, cron
`practice-pyq-admin.routes.ts`	practice-pyq-admin.routes.ts — Admin CRUD for practice catalogs
`practice-pyq-public.routes.ts`	practice-pyq-public.routes.ts — Learner practice catalog (PYQ + Practice YT)
`timestamps.route.ts`	timestamps.route.ts — Public merged video markers (admin + crowd)
`user.route.ts`	user.route.ts — Logged-in learner API (profile, library, playlists)

`services/`

File	What it does (short)
`continue-learning.service.ts`	CONTINUE LEARNING SERVICE — last 5 practiced subtopics with progress %
`current-affairs-ancillary.service.ts`	CURRENT AFFAIRS ANCILLARY — Nexus entities, search, PYQ links
`current-affairs-bookmark-news-revision.scheduler.ts`	BOOKMARK NEWS REVISION SCHEDULER — when bookmarked news items come due
`current-affairs-bookmark-news-revision.service.ts`	CA BOOKMARK NEWS REVISION — spaced review for bookmarked news snippets
`current-affairs-bookmark.service.ts`	CURRENT AFFAIRS BOOKMARK SERVICE — save news items for later + SRS row
`current-affairs-revision.service.ts`	CURRENT AFFAIRS REVISION SERVICE — MCQ/flashcard SRS queue for CA
`current-affairs.service.ts`	CURRENT AFFAIRS SERVICE — daily issues, news items, MCQs, flashcards
`google.service.ts`	GOOGLE SERVICE — verify Google Sign-In tokens
`marketing-deal-coupon.service.ts`	MARKETING DEAL COUPON — unique sponsor coupon codes
`practice-pyq-ce-asrs-scheduler.ts`	PRACTICE PYQ CE-ASRS SCHEDULER — exam-tuned SRS (ladder + phase II)
`practice-pyq-grade.ts`	PRACTICE PYQ GRADE — shared SRS button labels
`practice-pyq-learner.service.ts`	PRACTICE PYQ LEARNER SERVICE — public practice flow + SRS grading
`practice-pyq-questions.service.ts`	PRACTICE PYQ QUESTIONS SERVICE — admin CRUD + public question lists
`practice-pyq-srs-scheduler.ts`	PRACTICE PYQ SRS SCHEDULER — SM-2 style intervals from four grades
`practice-pyq-taxonomy.service.ts`	PRACTICE PYQ TAXONOMY SERVICE — subjects, topics, subtopics (admin + public tree)
`practice-pyq-week-review.service.ts`	PRACTICE PYQ WEEK REVIEW — kanban “this week” due cards by subtopic/day
`practice-review-summary.service.ts`	PRACTICE REVIEW SUMMARY — due today / overdue counts for review hub
`token.service.ts`	TOKEN SERVICE — login sessions (access + refresh JWT)
`youtube.service.ts`	YOUTUBE SERVICE — video/channel metadata for study content

`services/notifications/`

File	What it does (short)
`fcm-sender.service.ts`	FCM SENDER — deliver push notifications via Firebase Cloud Messaging
`notification-metrics.service.ts`	NOTIFICATION METRICS — admin dashboards for push campaigns
`notification-templates.ts`	NOTIFICATION TEMPLATES — push title/body copy (EN + HI)
`record-notification-open.service.ts`	RECORD NOTIFICATION OPEN — analytics when user taps a push
`send-due-reminders.service.ts`	SEND DUE REMINDERS — “you have revisions due” push campaign
`send-streak-warnings.service.ts`	SEND STREAK WARNINGS — evening push if streak at risk (no practice today)

`services/user-study-stats/`

File	What it does (short)
`record-practice-attempt-analytics.ts`	RECORD PRACTICE ATTEMPT ANALYTICS — streaks + rollups per attempt
`record-recent-practice-subtopic.ts`	RECORD RECENT PRACTICE SUBTOPIC — “continue learning” recency list
`study-stats-window.ts`	STUDY STATS WINDOW — IST day-key helpers for analytics range
`study-stats.service.ts`	STUDY STATS SERVICE — dashboard aggregates for a user

`types/`

File	What it does (short)
`index.ts`	TypeScript types are compile-time only — they disappear when JavaScript

`utils/`

File	What it does (short)
`ca-local-datetime.ts`	Current Affairs: local date/time without extra libraries
`current-affairs-date.ts`	Current Affairs date string validation
`current-affairs-search-expand.ts`	Current Affairs global search: query expansion
`dto.ts`	”DTO” = Data Transfer Object = the JSON shape we send to clients.
`india-study-calendar.ts`	India study calendar (single timezone for CA + PYQ week boards)
`localized-display-title.ts`	Localized display titles (English + Hindi)
`nexus-entity-status.ts`	Nexus entity status & MongoDB filters
`yt-solution-stored.ts`	Practice YT: `yt_solution` field normalization
`yt-solution-url.ts`	YouTube solution URL validation (Practice YT bulk import)

`validators/`

File	What it does (short)
`current-affairs.schemas.ts`	All request bodies/queries for daily issues, news items, MCQs, flashcards,
`notification.schemas.ts`	Request/query/body schemas for notification.route.ts. Validates before
`practice-pyq-public.schemas.ts`	Query/body for fetching question queues and grading attempts (SRS).
`practice-pyq-question.schemas.ts`	Validates bulk JSON paste into PracticePyqQuestion (flat PYQ fields + en/hi).
`practice-pyq-taxonomy.schemas.ts`	CALLED BY: practice-pyq-admin.routes, practice-pyq-taxonomy.service
`practice-review-summary.schemas.ts`	Query validation for GET /users/me/review-summary — home-screen badge
`user-study-stats.schemas.ts`	Validates GET /users/me/study-stats query params and documents the

Last updated on May 19, 2026

Overview src/ (root files)