System Requirements Document for gamma-scholar

1. Introduction

gamma-scholar (نبض الباحث / Scholar Pulse) is a unified academic-identity aggregator for researchers and university lecturers. It gathers a scholar's academic identities from multiple platforms into one place and delivers a precise, immediate signal whenever a new citation is recorded against their work.

The product intent, derived from the authoritative requirement thread, is:

• Unify academic identity. One interface links a researcher's accounts across Google Scholar, ORCID, Scopus, ResearchGate, and Web of Science.
• Alert on citations. Immediate in-app or email notifications when a new citation is detected for a paper, or when a new paper carrying the researcher's name is published.
• Show academic performance. A simple analytics dashboard with charts of citation growth over time and automatic updates of the h-index and i10-index.
• Share the profile. A single bio link or QR code that collects all of the lecturer's accounts, suitable for a CV or for sharing with students and colleagues.

The primary audience is Iraqi and Arab university faculty — researchers and lecturers who need credible, legible, authoritative information about their own scholarly record. The MVP is deliberately narrow: login, Google Scholar linking only, a dashboard showing papers and citations, and email or push notification when citations increase.

2. System Overview

gamma-scholar is a web application (PWA) with a Supabase-backed PostgreSQL data layer and scheduled Edge Functions. It aggregates citation and publication data from external academic providers, stores a baseline snapshot per linked account, re-checks every 24 hours, and raises a notification when a citation count increases.

Current delivery (MVP scope):

• Self-service account creation and login for the researcher/lecturer.
• Linking a Google Scholar account by entering the account URL or ID.
• Initial sync that pulls the current citation and publication counts and stores them as a baseline.
• A dashboard showing papers and citations, with a citation-growth chart and automatically updated h-index and i10-index.
• Email or push notification when a citation increase is detected.
• A shareable profile (bio link + QR code) that a visitor can open without an account.

Actors:

• الباحث / التدريسي (the researcher/lecturer) — the authenticated owner of the record.
• الزائر / الطالب أو الزميل المطّلع على الملف الشخصي (the visitor — student or colleague viewing the profile) — an unauthenticated reader of a shared profile.

External providers (non-persona actors): Semantic Scholar API, CrossRef API, ORCID API, SerpApi (Google Scholar), and the email/push delivery channel.

Narrow exclusions for the current horizon: the MVP links Google Scholar only. ORCID, Scopus, ResearchGate, and Web of Science are part of the stated product intent but are outside the current MVP linking scope. Google Scholar has no official API and imposes strict web-scraping limits; SerpApi is used only to fetch the h-index from Google Scholar, to reduce cost and IP blocking. Semantic Scholar and CrossRef are the priority sources because they offer official, free APIs. Name disambiguation is handled primarily through the ORCID identifier.

2a. Product Interpretation and Delivery Boundary

gamma-scholar is a first-party application that owns its own identity and durable state. The researcher creates an account, links an academic source, and the application stores a baseline and a history of citation counts against that account. Because the record must persist across sessions and be bound to the correct researcher, application-owned identity is required: the landing page and login are anonymously reachable, while the dashboard, account linking, and profile sharing require a logged-in session. The public profile is deliberately anonymous — a visitor opens the bio link or scans the QR code and reads the aggregated accounts, papers, and citations without creating an account.

Background automation (the 24-hour check) runs server-side and produces a notification; the researcher's interaction with that notification is a first-party surface, not a background step. External providers own the fetching of citation and publication data; the application owns the aggregation, the baseline comparison, and the alert.

The current horizon covers the MVP as listed above. The broader five-platform linking, ORCID-based disambiguation, and the additional providers remain part of the product intent but are not part of the current MVP linking scope.

2b. Source Content Inventory

Not applicable — no reference directive in this request declares a content_source.

2c. Page Content and Component Coverage

Landing

• Information/state: Public entry surface. Explains what نبض الباحث / Scholar Pulse is, who it is for, and what it does before any login or protected work. Presents the product as a citation wayfinding system for a scholar's record.
• Primary actions: Navigate to Login to create an account or sign in.
• Supporting actions: Read the wayfinding sequence (01 REGISTER, 02 SYNC, 03 ALERT, 04 SHARE) as a ruled horizontal sequence with numbered nodes and 1px connectors.
• Domain entities: Product description, the four-step workflow (register → baseline → 24h check → alert), the platform code tiles (GS, OR, SC, RG, WoS).
• Component responsibilities: Hero headline block (oversized Arabic headline, three stacked flush-left lines, third line in a solid primary-red block bleeding off the right edge); a 2px black rule at the top with an all-caps label; a ruled four-column metric bar (h-index, i10-index, total citations, linked sources) with tabular numerals and all-caps labels; a full-width 2px rule with a numbered section marker in the left margin for each section transition; a ruled sync-workflow diagram.
• States: Loading — not applicable (static entry). Empty — not applicable. Success — page renders fully. Error — not applicable. Recovery — not applicable.

Login

• Information/state: Anonymous identity-access surface. Enables the researcher/lecturer to create an account and sign in, covering self-service registration and returning verification.
• Primary actions: Create an account (self-service registration); sign in with existing credentials.
• Supporting actions: Switch between registration and sign-in; recover access when credentials are not accepted.
• Domain entities: Researcher account (email/credential), session.
• Component responsibilities: Registration form; sign-in form; credential validation feedback; error and recovery messaging.
• States: Loading — submission in progress. Empty — no credentials entered. Success — session established, redirect to the dashboard. Error — invalid credentials or registration conflict, with a recovery path. Recovery — re-enter credentials or restart registration.

لوحة التحكم

• Information/state: Authenticated dashboard. Shows the researcher's papers and citations, a citation-growth chart over time, and the automatically updated h-index and i10-index. Tabular layout: each linked platform gets a fixed column with aligned label/value rows.
• Primary actions: Review papers and citation counts; read the citation-growth chart; read the h-index and i10-index.
• Supporting actions: Navigate to ربط الحسابات to link a source; navigate to مشاركة الملف to share the profile; open a notification.
• Domain entities: Paper, citation count, citation-growth series, h-index, i10-index, linked source, baseline snapshot, notification.
• Component responsibilities: Ruled metric bar (h-index in red, i10-index in amber, new publications in green); citation-growth chart as solid red bars in a ruled plot area with a 2px black h-index line and all-caps year labels; ruled paper/citation table with 1px horizontal rules; platform code tiles; notification badge.
• States: Loading — data being fetched. Empty — no linked source or no papers yet, with a prompt to link an account. Success — papers, citations, chart, and indices displayed. Error — provider fetch failure, with a retry path. Recovery — retry the fetch or re-link the source.

ربط الحسابات

• Information/state: Authenticated linking surface. Enables the researcher to link a Google Scholar account by entering the account URL or ID.
• Primary actions: Enter the Google Scholar account URL or ID; submit the link.
• Supporting actions: Review the linked source; re-link or correct the URL/ID.
• Domain entities: Linked academic account (Google Scholar), account URL/ID, baseline snapshot.
• Component responsibilities: URL/ID input; submit control; linked-source display with a platform code tile; baseline confirmation.
• States: Loading — link submission and initial sync in progress. Empty — no source linked yet. Success — source linked and baseline stored. Error — invalid URL/ID or provider fetch failure, with a recovery path. Recovery — correct the URL/ID and resubmit.

مشاركة الملف

• Information/state: Authenticated sharing surface. Generates a single bio link and a QR code that collect the researcher's academic accounts for sharing with students and colleagues.
• Primary actions: Generate and copy the bio link; display the QR code.
• Supporting actions: Preview the public profile; share the link or QR code.
• Domain entities: Bio link, QR code, aggregated academic accounts.
• Component responsibilities: QR code block framed by a 2px black rule with a corner tick; bio link in monospace; ruled list of linked platform codes.
• States: Loading — link/QR generation in progress. Empty — no linked accounts to share yet. Success — bio link and QR code displayed. Error — generation failure, with a retry path. Recovery — retry generation.

الملف الشخصي

• Information/state: Anonymous public profile. Displays the aggregated academic accounts, papers, and citations to a visitor who opens the bio link or scans the QR code, without requiring an account.
• Primary actions: Read the aggregated accounts, papers, and citations.
• Supporting actions: Follow a linked academic account.
• Domain entities: Aggregated academic accounts, papers, citations, h-index, i10-index.
• Component responsibilities: Single centred artefact — QR code, bio link in monospace, ruled list of linked platform codes, ruled paper/citation list.
• States: Loading — profile data being fetched. Empty — no linked accounts or papers. Success — profile displayed. Error — profile not found or fetch failure. Recovery — retry or return to the landing page.

3. Functional Requirements

FR-1 — Unified academic identity aggregator (explicit) As a researcher/lecturer, I should have a single platform that gathers my academic identities in one place, so that my scholarly record is unified rather than scattered across platforms.

• Trigger/input: the researcher has accounts on one or more academic platforms.
• Observable result: the application presents the researcher's academic identities in one place.
• Access state: authenticated.
• Failure/recovery: if a source cannot be fetched, the application reports the failure and allows a retry.
• Continuation: the researcher proceeds to link accounts or view the dashboard.

FR-2 — Link accounts across five platforms (explicit) As a researcher/lecturer, I should link my accounts on Google Scholar, ORCID, Scopus, ResearchGate, and Web of Science through one interface, so that all of my academic identities are connected.

• Trigger/input: the researcher enters the account URL or ID for each platform.
• Observable result: each linked account is recorded and displayed.
• Access state: authenticated.
• Failure/recovery: an invalid URL/ID or provider failure is reported, and the researcher can correct and resubmit.
• Continuation: the researcher views the aggregated record on the dashboard.
• Note: the current MVP links Google Scholar only; the other four platforms are part of the stated product intent but outside the current MVP linking scope.

FR-3 — Citation alerts (explicit) As a researcher/lecturer, I should receive immediate in-app or email notifications when a new citation is detected for one of my papers, or when a new paper carrying my name is published, so that I learn about new impact on my work without checking manually.

• Trigger/input: a new citation or a new publication is detected.
• Observable result: an in-app or email notification is delivered.
• Access state: authenticated.
• Failure/recovery: if delivery fails, the notification remains available in-app and can be re-sent.
• Continuation: the researcher opens the notification and reviews the cited paper.

FR-4 — Analytics dashboard (explicit) As a researcher/lecturer, I should see simple charts of my citation growth over time, with my h-index and i10-index updated automatically, so that I can track my academic performance.

• Trigger/input: the researcher opens the dashboard.
• Observable result: a citation-growth chart and the current h-index and i10-index are displayed.
• Access state: authenticated.
• Failure/recovery: if data cannot be fetched, the dashboard reports the failure and offers a retry.
• Continuation: the researcher reviews the chart and indices.

FR-5 — Profile sharing (explicit) As a researcher/lecturer, I should have a single bio link or QR code that collects all of my accounts, so that I can place it in my CV or share it with my students and colleagues.

• Trigger/input: the researcher generates the bio link or QR code.
• Observable result: a single bio link and QR code are produced.
• Access state: authenticated.
• Failure/recovery: if generation fails, the researcher can retry.
• Continuation: the researcher shares the link or QR code.

FR-6 — Registration and linking workflow (explicit) As a researcher/lecturer, I should create my account and enter the links or IDs of my academic accounts, so that the application can begin tracking my record.

• Trigger/input: the researcher registers and enters account links/IDs.
• Observable result: the account is created and the links are recorded.
• Access state: anonymous entry, then authenticated.
• Failure/recovery: invalid input or registration conflict is reported with a recovery path.
• Continuation: the researcher proceeds to initial sync.

FR-7 — Initial sync (explicit) As a researcher/lecturer, I should have the application pull my current citation and publication counts and store them as a baseline, so that future changes can be compared against a known starting point.

• Trigger/input: the researcher links an account.
• Observable result: the current counts are stored as a baseline in the database.
• Access state: authenticated.
• Failure/recovery: if the pull fails, the researcher is informed and can retry.
• Continuation: the baseline is used for the 24-hour comparison.

FR-8 — Periodic 24-hour check (explicit) As a researcher/lecturer, I should have the servers send requests to the APIs every 24 hours to compare the new count against the stored count, so that changes are detected without my intervention.

• Trigger/input: the 24-hour schedule elapses.
• Observable result: the new count is compared against the stored count.
• Access state: system process (no human interaction).
• Failure/recovery: a failed check is logged and retried on the next cycle.
• Continuation: a detected increase triggers a notification.

FR-9 — Notification dispatch (explicit) As a researcher/lecturer, I should receive a notification when a citation increase is detected, with the details of the citing paper, so that I know exactly what was cited and by which study.

• Trigger/input: a citation increase is detected.
• Observable result: a notification is sent with the message "تهانينا! تم الاستشهاد ببحثك [اسم البحث] في دراسة جديدة بعنوان [اسم الدراسة الجديدة]".
• Access state: authenticated.
• Failure/recovery: if delivery fails, the notification remains available in-app.
• Continuation: the researcher opens the notification and reviews the citing study.

FR-10 — MVP scope (explicit) As a researcher/lecturer, I should have the first version include only login, Google Scholar linking, a dashboard showing papers and citations, and email or push notification on citation increase, so that the initial release is focused.

• Trigger/input: the researcher uses the MVP.
• Observable result: only the MVP features are available.
• Access state: as per each feature.
• Failure/recovery: as per each feature.
• Continuation: as per each feature.

FR-11 — Account creation and login (required_inference) As a researcher/lecturer, I should create an account and sign in to it, so that my record is bound to me and persists across sessions.

• Trigger/input: the researcher submits registration or sign-in credentials.
• Observable result: a session is established and the researcher reaches the dashboard.
• Access state: anonymous entry; authenticated after success.
• Failure/recovery: invalid credentials or a registration conflict are reported with a recovery path.
• Continuation: the researcher links an account or views the dashboard.

FR-12 — Google Scholar linking by URL/ID (required_inference) As a researcher/lecturer, I should link my Google Scholar account by entering its URL or ID, so that the application can track my record on that platform.

• Trigger/input: the researcher enters the Google Scholar account URL or ID.
• Observable result: the account is linked and displayed.
• Access state: authenticated.
• Failure/recovery: an invalid URL/ID or provider failure is reported, and the researcher can correct and resubmit.
• Continuation: the researcher proceeds to initial sync.

FR-13 — Baseline capture on linking (required_inference) As a researcher/lecturer, I should have the current citation and publication counts pulled and stored as a baseline when I link my account, so that future changes are measured against it.

• Trigger/input: the researcher links an account.
• Observable result: the baseline is stored.
• Access state: authenticated.
• Failure/recovery: if the pull fails, the researcher is informed and can retry.
• Continuation: the baseline is used for the 24-hour comparison.

FR-14 — 24-hour periodic check (required_inference) As a researcher/lecturer, I should have the system check the providers every 24 hours, so that citation changes are detected automatically.

• Trigger/input: the 24-hour schedule elapses.
• Observable result: the new count is compared against the stored count.
• Access state: system process.
• Failure/recovery: a failed check is logged and retried on the next cycle.
• Continuation: a detected increase triggers a notification.

FR-15 — Notification or email on citation increase (required_inference) As a researcher/lecturer, I should receive a notification or email when a citation increase is detected, so that I am informed promptly.

• Trigger/input: a citation increase is detected.
• Observable result: a notification or email is delivered.
• Access state: authenticated.
• Failure/recovery: if delivery fails, the notification remains available in-app.
• Continuation: the researcher opens the notification and reviews the citing study.

4. User Personas

الباحث / التدريسي (The Researcher / Lecturer)

• Product context: A university researcher or lecturer in Iraq or the Arab region who maintains academic accounts across platforms and wants to follow the impact of their own work. Google Scholar is the most widely used platform in Iraqi and Arab universities, which is why it is the MVP linking target.
• Primary goal: To see, in one place, how their papers are being cited and to be alerted immediately when a new citation or a new paper carrying their name appears.
• Distinct accepted responsibilities: Registers and signs in; links their Google Scholar account by URL or ID; has the current citation and publication counts pulled and stored as a baseline; reviews papers, citations, the citation-growth chart, and the automatically updated h-index and i10-index on the dashboard; receives and opens notifications when a citation increase is detected; generates and shares a bio link or QR code with students and colleagues.
• Relevant inputs or decisions: The Google Scholar account URL or ID; the decision to link or re-link a source; the decision to share the profile.
• Interactions with other accepted participants: Shares the bio link or QR code with students and colleagues, who then view the public profile. Receives notifications produced by the background 24-hour check.
• Observable success: The dashboard shows papers, citations, the citation-growth chart, and current h-index and i10-index; a notification arrives when a citation increase is detected; the bio link and QR code resolve to a public profile.

الزائر / الطالب أو الزميل المطّلع على الملف الشخصي (The Visitor — Student or Colleague Viewing the Profile)

• Product context: A student or colleague who receives the researcher's bio link or scans the QR code and wants to see the researcher's aggregated academic accounts, papers, and citations.
• Primary goal: To read the researcher's aggregated academic record without creating an account or linking any accounts.
• Distinct accepted responsibilities: Opens the bio link or scans the QR code; reads the aggregated academic accounts, papers, and citations; follows a linked academic account.
• Relevant inputs or decisions: The bio link or QR code; the decision to follow a linked account.
• Interactions with other accepted participants: Receives the bio link or QR code from the researcher/lecturer.
• Observable success: The public profile displays the aggregated accounts, papers, and citations without requiring an account.

5. Core User Flows

Flow 1 — Researcher registers and signs in

1. The researcher/lecturer opens the Landing page and reads what نبض الباحث / Scholar Pulse is, who it is for, and what it does.
2. The researcher selects the action to create an account or sign in and arrives at Login.
3. The researcher submits registration details (or existing credentials) on Login.
4. The application validates the submission. On success, a session is established and the researcher is taken to لوحة التحكم. On failure (invalid credentials or a registration conflict), Login reports the error and the researcher re-enters credentials or restarts registration.
5. The researcher continues to link an academic account or review the dashboard.

Flow 2 — Researcher links a Google Scholar account and captures a baseline

1. From لوحة التحكم, the researcher navigates to ربط الحسابات.
2. The researcher enters the Google Scholar account URL or ID and submits the link.
3. The application records the linked account and pulls the current citation and publication counts, storing them as a baseline.
4. On success, ربط الحسابات displays the linked source with its platform code tile and confirms the baseline. On failure (invalid URL/ID or provider fetch failure), the page reports the error and the researcher corrects the URL/ID and resubmits.
5. The researcher returns to لوحة التحكم to review the record.

Flow 3 — Researcher reviews the analytics dashboard

1. The researcher opens لوحة التحكم.
2. The dashboard displays papers and citations, a citation-growth chart over time, and the automatically updated h-index and i10-index.
3. If data cannot be fetched, the dashboard reports the failure and offers a retry; the researcher retries or re-links the source.
4. The researcher reviews the chart and indices and continues to share the profile or wait for notifications.

Flow 4 — Researcher receives a citation alert

1. The background 24-hour check compares the new citation count against the stored baseline.
2. When an increase is detected, the application fetches the details of the citing paper and sends a notification: "تهانينا! تم الاستشهاد ببحثك [اسم البحث] في دراسة جديدة بعنوان [اسم الدراسة الجديدة]".
3. The researcher receives the notification in-app or by email.
4. If delivery fails, the notification remains available in-app and can be re-sent.
5. The researcher opens the notification and reviews the citing study, then returns to لوحة التحكم.

Flow 5 — Researcher shares the profile

1. From لوحة التحكم, the researcher navigates to مشاركة الملف.
2. The researcher generates the bio link and QR code that collect their academic accounts.
3. On success, مشاركة الملف displays the QR code framed by a 2px black rule with a corner tick, the bio link in monospace, and a ruled list of linked platform codes. On failure, the researcher retries generation.
4. The researcher copies the bio link or shares the QR code with students and colleagues.

Flow 6 — Visitor views the public profile

1. The visitor (student or colleague) opens the bio link or scans the QR code and arrives at الملف الشخصي.
2. The public profile displays the aggregated academic accounts, papers, and citations without requiring an account.
3. If the profile is not found or data cannot be fetched, the page reports the error and the visitor retries or returns to the Landing page.
4. The visitor reads the record and may follow a linked academic account.

6. Visuals, Colors and Theme

The creative direction is authoritative for this section. The muse is Massimo Vignelli; the headline is Citation wayfinding: a signage system for a scholar's record.

Color tokens (light mode):

Proportion: roughly 70% white, 20% black type and rules, 10% coded colour. No gradients anywhere. Colour is never decorative — every colour instance means a data category or a state.

Typography:

• Headings: Archivo, single heavy weight (700), flush-left ragged-right, tight tracking (-0.02em), sentence case for editorial headlines and all-caps for system labels. No light weights, no display serif, no expressive letterforms.
• Body: Archivo.
• Scale: 1.333 modular scale — 56/42/32/24/18/16/14/12.
• Hero display: clamp(56px, 9vw, 128px) at 700 weight.
• Section headings: clamp(32px, 4vw, 56px).
• Data numerals: 42px tabular at 700 for h-index and i10-index; 24px for citation counts.
• Body 16px; metadata 13px all-caps with 0.08em tracking.
• Line height: 1.15 for display, 1.5 for body.

Shape language: Hard edges. Zero border-radius on cards, panels, buttons, and inputs — every corner is 90 degrees. Structure is expressed through 1px and 2px black rules: horizontal rules separate every data row, vertical rules divide the dashboard into columns, and a 2px rule anchors the top of every section like a signage band. Buttons are rectangles with a 2px black border and a solid fill on hover. The QR code block is framed by a 2px black rule with a corner tick, like a printed registration mark. No shadows, no blurs, no rounded controls.

Layout: A visible 12-column grid with a 24px gutter and generous 48px outer margins at desktop, collapsing to 4 columns at 375px. The dashboard is tabular: each platform gets a fixed column with aligned label/value rows. Section transitions are marked by full-width 2px rules with a small all-caps section number in the left margin (01, 02, 03). The citation-growth chart sits in a ruled plot area with axis ticks and no gridlines behind the bars — bars are solid primary red, the h-index line is a 2px black rule. The profile share page is a single centred artefact: the QR code, the bio link in monospace, and a ruled list of linked platform codes below it. No card grids, no offset shadows, no floating panels.

Imagery: No photography, no illustration, no 3D. The visual content is the system itself: the grid, the rules, the coded colour chips, the tabular data, the QR code, and the citation chart. Where an image is needed — a platform's logo — it is reduced to a monochrome pictogram or a two-letter code in a ruled square (GS, OR, SC, RG, WoS). The hero contains no image at all; its dominant element is the type. Diagrams of the sync workflow (register → baseline → 24h check → alert) are drawn as a ruled horizontal sequence with numbered nodes and 1px connectors.

7. Signature Design Concept

The public entry (Landing) is a full-viewport white field with a 2px black rule running horizontally at the top, under which sits a small all-caps label: نبض الباحث / SCHOLAR PULSE — CITATION WAYFINDING SYSTEM.

The dominant element is an oversized Arabic headline set flush-left in three stacked lines, clamp(56px, 9vw, 128px), black, with the third line dropped into a solid primary-red block that bleeds off the right edge of the viewport — the red block is the only large area of colour on the screen. Beneath the headline, a 1px black rule spans the full width, and below it a four-column ruled row of live-looking metrics (h-index, i10-index, total citations, linked sources) with tabular numerals and all-caps labels. No centred composition, no subtext paragraph, no blue button, no gradient, no image — the type and the rules are the hero.

The signature moves are: the oversized Arabic headline stacked flush-left across three lines with the final line set in a solid red block that bleeds off the right viewport edge; a ruled metric bar directly under the hero with four columns divided by 1px vertical rules, each showing a label in 13px all-caps, a value in 42px tabular numerals, and a small colour code chip (red for h-index, amber for i10, green for new publications); every platform integration represented by a ruled square containing a two-letter code (GS, OR, SC, RG, WoS) instead of a logo; the citation chart drawn as solid red bars against a ruled plot area with a 2px black h-index line overlaid and every bar labelled with its year in all-caps beneath the axis; and section transitions using a full-width 2px rule with a numbered marker in the left margin (01 REGISTER, 02 SYNC, 03 ALERT, 04 SHARE), turning the landing page into a wayfinding sequence rather than a stack of feature cards.

8. Interaction Model & Motion Direction

Interaction Model: Static (direction) Motion Tempo: still Hero Dimensionality: flat

Landing Hero Motion Brief

• Focal subject: The oversized Arabic headline stacked flush-left across three lines, with the third line in a solid primary-red block bleeding off the right viewport edge.
• Input → transformation → outcome thesis: On load, a single line rule draws left-to-right under the hero headline over 600ms; the citation chart bars scale up from the baseline once when scrolled into view. No other motion is present.
• Motion vocabulary: Minimal and instant. State changes are immediate: a citation count increments with no easing, a notification badge appears without bounce, a syncing row flips from amber to green in one frame. Hover states are instant colour inversions (white to black, or white to primary red), never transitions longer than 120ms. No parallax, no marquees, no scroll-linked animation.
• Composed first frame: White field; 2px black rule at the top with the all-caps label; the three-line Arabic headline flush-left; the 1px rule beneath; the four-column ruled metric bar with tabular numerals and colour code chips.
• Reduced-motion state: The line rule and chart bars render in their final state immediately; no animation plays. All content remains fully readable and all controls remain usable.

9. Non-Functional Requirements

• NFR-1 — Provider priority (explicit): Semantic Scholar and CrossRef are the priority sources for fetching research and citation data because they offer official, free APIs. Rationale: reliability and cost control.
• NFR-2 — Google Scholar scraping constraint (explicit): Google Scholar has no official API and imposes strict web-scraping limits; SerpApi is used only to fetch the h-index from Google Scholar, to reduce cost and IP blocking. Rationale: avoid IP blocking and cost escalation.
• NFR-3 — Name disambiguation (explicit): Name disambiguation is handled primarily through the ORCID identifier as the primary standard for linking a researcher to their real papers, away from name similarity. Rationale: accuracy of attribution.
• NFR-4 — Scheduled checks (explicit): The servers send requests to the APIs every 24 hours to compare the new count against the stored count. Rationale: timely detection without manual checking.
• NFR-5 — Notification delivery (explicit): Notifications are delivered in-app or by email. Rationale: reach the researcher on their preferred channel.
• NFR-6 — Data persistence (required_inference): The baseline and citation history are stored in PostgreSQL so that comparisons and the dashboard survive across sessions. Rationale: the 24-hour comparison and the dashboard require durable state.
• NFR-7 — Access control (required_inference): The dashboard, account linking, and profile sharing require a logged-in session; the landing page, login, and public profile are anonymously reachable. Rationale: the record must be bound to the correct researcher, while the public profile is intended for sharing without an account.

10. Tech Stack

• Frontend: React, delivered as a Progressive Web App (PWA) so it is accessible without app-store constraints. (explicit)
• Backend and database: Supabase for authentication and PostgreSQL for storing researcher records, with Edge Functions for scheduled cron jobs that look for new citations. (explicit)
• Data fetching and APIs: Semantic Scholar API and CrossRef API for research and citation data; ORCID API for linking the researcher's identity and pulling their publication record; SerpApi (Google Scholar API) for fetching the h-index from Google Scholar. (explicit)
• Notifications: In-app push and email delivery. (explicit)
• Deployment: Docker/docker-compose for the application services. (Default — not specified by user)

11. Assumptions and Constraints

• MVP scope constraint (explicit): The first version includes only login, Google Scholar linking, a dashboard showing papers and citations, and email or push notification on citation increase.
• Google Scholar constraint (explicit): Google Scholar has no official API and imposes strict web-scraping limits; SerpApi is used only for the h-index.
• Provider priority constraint (explicit): Semantic Scholar and CrossRef are the priority sources because they offer official, free APIs.
• Name disambiguation constraint (explicit): ORCID is the primary standard for linking a researcher to their real papers.
• Assumption — current linking scope (required_inference): The current MVP links Google Scholar only; ORCID, Scopus, ResearchGate, and Web of Science remain part of the product intent but are outside the current MVP linking scope.
• Assumption — identity continuity (required_inference): Application-owned identity is required so that the baseline, citation history, and notifications remain bound to the correct researcher across sessions.
• Assumption — public profile (required_inference): The public profile is anonymously reachable by design, so that students and colleagues can view it without creating an account.

12. Glossary

• نبض الباحث / Scholar Pulse: The product name; a unified academic-identity aggregator with citation alerts.
• gamma-scholar: The project name for this system.
• Aggregator: A platform that gathers a researcher's academic identities from multiple sources into one place.
• Citation: A reference to a researcher's paper in another study.
• Citation alert: A notification delivered when a new citation is detected for a paper, or when a new paper carrying the researcher's name is published.
• h-index: A metric reflecting both the productivity and citation impact of a researcher's publications.
• i10-index: A metric counting the number of publications with at least ten citations.
• Baseline: The stored snapshot of a researcher's current citation and publication counts, used as the starting point for future comparisons.
• Bio link: A single shareable URL that collects a researcher's academic accounts.
• QR code: A scannable code that resolves to the researcher's public profile.
• Google Scholar: An academic search platform without an official API; linked in the MVP.
• ORCID: A persistent digital identifier for researchers, used as the primary standard for name disambiguation.
• Semantic Scholar / CrossRef: Official, free APIs used as the priority sources for research and citation data.
• SerpApi: A service used to fetch the h-index from Google Scholar.
• Supabase: The backend platform providing authentication, PostgreSQL, and Edge Functions for scheduled jobs.
• Edge Functions: Server-side functions used to run the scheduled cron jobs that check for new citations.
• PWA: Progressive Web App; the delivery form of the frontend.