Detailed Documentation
Complete reference for functionality, architecture, APIs, services, limitations, and roadmap.
Features
Capability-level overview by product area.
Shortcut Hints
Keyboard and command prefix usage.
Changelog
Version-by-version release details.
Request path from catalog/personal discovery to offline and organization operations.
- Catalog APIs provide department, semester, and course metadata for global repository navigation.
- Personal Repository workflows run local-first with persisted state, local scans, and IndexedDB-backed stores.
- Add Folder uses a unified link-input flow (Studytrix import link or Drive folder link) plus optional device-folder source.
- Command Center indexes files/folders and switches scopes using `/`, `#`, `:`, `>`, and `@`.
- Offline actions persist file blobs using File System Access API or IndexedDB fallback.
- Smart shelves (Smart Collections, pinned files, Study Sets) are generated from personal index/store state.
- Version and changelog modules inform users when a new build is available.
How UI, stores, and feature controllers coordinate behavior.
- Next.js App Router renders shell-level layout and route pages.
- Zustand stores hold settings, offline index state, command state, and transfer state.
- Feature modules are domain-scoped (`features/command`, `features/offline`, `features/bulk`, `features/download`).
- Dialogs are used for long-running operations to provide persistent progress and completion feedback.
- The Settings system is schema-driven and searchable by category.
- Greeting preferences are persisted as a typed object in the settings store.
- No user account/login/authentication runtime is required for app usage.
Local-first orchestration for personal folders, shelves, and capture flows.
- Folder sources include unified link import, device folders, and app-created local folders.
- Source kind is tracked per folder (`drive`, `local`, `local-virtual`) with safe hydration defaults.
- Local handles are persisted in IndexedDB and re-verified on app init/visibility.
- Smart Collections, pinned files, and Study Sets are store-driven and persisted locally.
- Quick Capture flows write locally first and update personal indexing paths incrementally.
- Folder health and reconnect UX are derived from sync metadata and permission status.
How server routes proxy global repository/catalog operations and link validation.
- Global repository Drive and file APIs run in Node.js runtime route handlers.
- Route handlers validate identifiers and normalize error responses.
- Custom-folder link resolve endpoint decodes and validates import link payloads.
- Catalog routes read and validate `data/catalog.json` before returning course data.
- Response errors are intentionally generic for internal failures.
Time-period and weather-aware greeting generation for the dashboard.
- Greeting engine generates `primaryMessage` and `secondaryMessage` for six daily time windows.
- Optional weather integration uses Open-Meteo (`/v1/forecast`) `current_weather.weathercode` mapping.
- Theme options branch secondary content: study, motivational, and minimal (primary-only).
- Personalization supports named and anonymous greeting headline variants.
- Weather-aware study nudges are conditionally appended for non-default weather states.
Persistence model for offline-first operation.
- Primary strategy: File System Access API for explicit folder-backed storage where supported.
- Fallback strategy: IndexedDB persistence on unsupported/restricted platforms.
- Offline Library includes a static fallback page (`/offline-library.html`) that can read cached files directly from IndexedDB when route bundles are unavailable offline.
- Offline index and metadata are updated from local persistence operations.
- Storage location configuration supports setup, relink, and migration workflows.
- Offline search and availability indicators are derived from locally indexed content.
Command Center behavior and scoped search model.
- Global scope searches across workspace-level indexed entities.
- Local scope narrows results to current folder hierarchy context.
- Prefix shortcuts map to scoped intents: folder (`/`), tag (`#`), domain (`:`), actions (`>`), recents (`@`).
- Nested folder indexing improves deep file discovery in local and global flows.
- Code-aware result rendering and actions improve developer/stem file workflows.
- Keyboard-first navigation supports fast command execution across pages.
How the app handles mixed selection operations reliably.
- Selection preparation resolves folders into nested file entries before zip/share.
- Supported selection types include files-only, folder-only, and mixed file/folder sets.
- ZIP generation is client-side and optimized for predictable feedback during preparation.
- Copy/download actions are available for both files and folders with local-first fallbacks.
- Share flows use native Web Share where available with fallback paths when unavailable.
- Partial failures are surfaced explicitly instead of silently skipped.
Installability and SEO improvements for web and mobile entry points.
- App metadata includes richer Open Graph, Twitter card, robots, and canonical values.
- Route-level page metadata improves discoverability for features, docs, changelog, settings, and tags.
- Manifest files include launcher shortcuts, refined descriptions, and updated app icon assets.
- Favicon set is aligned across browser tabs, installed PWA icons, and Apple touch surfaces.
- Service worker shell cache includes offline fallback pages and redirects `/offline-library` navigation to offline-safe fallback content when requests fail.
How releases and product references are presented in-app.
- Current app version is declared in `features/version/version.ts`.
- Release entries are curated in `features/changelog/changelog.catalog.ts`.
- Update banner appears after version bumps with dismiss persistence in local storage.
- Guide pages include Changelog, Features, Shortcut Hints, and Documentation.
- Settings provides direct links to these guide pages for discoverability.
Public route handlers currently used by dashboard, file manager, command, and metadata flows.
Returns departments with only semesters that have valid Drive-backed content.
Success Response
200 with `{ departments: [{ id, name, availableSemesters[] }] }`.
Error Cases
- 500 internal error
Notes
- Uses `data/catalog.json` with server-side filtering.
- Returns cache headers (`max-age` + `stale-while-revalidate`).
Returns course list for a validated department and semester.
Success Response
200 with `{ courses: [...] }`.
Error Cases
- 400 invalid department or semester format
- 404 department not found
- 404 semester not found
- 500 internal error
Notes
- Department and semester params are decoded and strictly validated.
- Catalog schema is checked before returning data.
Decodes and validates a Studytrix share/import `fid` into a Drive folder ID.
Success Response
200 with `{ folderId }`.
Error Cases
- 400 `{ error: 'INVALID_LINK' }`
Notes
- Validates base64url payload and Drive-folder-id shape.
- Performs decode/validation only; no Drive API call is executed in this route.
Runs folder verification checks for Personal Repository Drive-link imports.
Success Response
200 with verification payload: `folderId`, `folderName`, `fileCount`, `folderCount`, `permissionLevel`, and safety flags.
Error Cases
- 400 invalid or unsupported folder ID
- 403 access denied/private folder
- 404 folder not found
- 502 upstream Drive error
Notes
- Verification route is read-only and does not write to Drive.
- Used by Add Folder and import-link flows before a folder is added locally.
Lists folder contents through Drive proxy with dedupe, cache, and rate limiting.
Success Response
200 with paginated folder items and optional `nextPageToken`.
Error Cases
- 400 invalid folder ID or page token
- 403 folder access denied
- 404 folder not found
- 429 rate limit exceeded
- 500 internal error
Notes
- Request dedupe prevents duplicate concurrent list calls.
- Cache-first behavior backed by Redis with in-memory fallback.
Builds nested file index from multiple root folders for deep command search.
Success Response
200 with `{ files, indexedAt, truncated }`.
Error Cases
- 400 invalid JSON payload
- 403 folder access denied
- 404 folder not found
- 500 failed to build nested index
Notes
- Payload accepts roots: `{ folderId, courseCode, courseName }`.
- Protective limits: max 64 roots, 4000 folders, 30000 files, concurrency 4.
Returns normalized file metadata used by preview and actions.
Success Response
200 with `{ metadata }`.
Error Cases
- 400 invalid file ID
- 403 file access denied
- 404 file not found
- 429 rate limit exceeded
- 500 internal error
Notes
- Shares the same Drive rate-limit guard as folder routes.
- Used by file preview and operation pipelines.
Streams file content with safe headers and Google-file export support.
Success Response
200/206 streamed response with content headers.
Error Cases
- 400 invalid ID or unsupported folder stream
- 403 file access denied
- 404 file not found
- 415 unsupported export type
- 416 unsupported range for exported docs
- 429 rate limited
- 503 upstream unavailable
- 500 internal error
Notes
- Exports Google Docs/Sheets/Slides/Drawing to standard formats before stream.
- Range requests are supported for direct media streams, not export streams.
Current constraints based on platform APIs and runtime boundaries.
- File System Access API support varies by browser and OS, especially on mobile PWAs.
- Native file sharing behavior differs by platform and can impose file count/size constraints.
- Large ZIP generation can be limited by device memory and browser execution budgets.
- Offline metadata freshness depends on sync/update cadence and storage permission continuity.
- Background sync behavior is browser-dependent and cannot be assumed uniform across all devices.
High-value areas planned for deeper reliability and capability.
- Deeper command intelligence and semantic ranking for nested content discovery.
- Richer storage diagnostics with guided recovery actions for permission and migration issues.
- More robust mobile-first workflows for long-running offline/share/zip operations.
- Expanded observability around partial failures, retries, and transfer bottlenecks.
- More export/share options for batch workflows and collaborative distribution.
Common issues and first-response checks.
- If folder listings fail with `429`, wait for rate-limit window reset and retry.
- If offline files disappear after permission changes, reopen storage settings and relink location.
- If sharing is unavailable, verify platform Web Share support and use copy-link fallback.
- If ZIP preparation is slow, reduce selection size or split very large mixed batches.
- If nested results are missing, trigger nested index refresh by reopening scoped search context.