# coe-nthu/ipedu_scholarship_system architecture

> Architecture diagram of the GitHub repository coe-nthu/ipedu_scholarship_system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coe-nthu/ipedu_scholarship_system
- Repository: https://github.com/coe-nthu/ipedu_scholarship_system

## Overview

1. This is a Next.js App Router repository with a clear split between server-rendered pages, client-facing interactive components, and API route handlers under `app/`. The root layout and global styles live in `app/layout.tsx` and `app/globals.css`, and the top-level UI is composed from page routes rather than a separate backend service.

2. The public-facing scholarship site is organized as a set of program-specific pages under `app/scholarships/*` plus a scholarship selection client component. These pages are likely the entry point for applicants to choose a program and submit data, with shared form/configuration logic kept in `lib/scholarship-*` modules.

3. Scholarship application submission is handled by dedicated API routes under `app/api/scholarships/*`. The key flow appears to be: applicant form data goes to the scholarship API, file uploads are coordinated through an `upload-url` endpoint, and a `confirmation-email` endpoint sends transactional confirmation after submission.

4. The administrative back office lives in `app/dashboard/*` and is backed by a larger set of dashboard APIs under `app/api/dashboard/*`. This includes login/logout, password reset and password change, account management, authorized email management, scholarship program management, journal indexes, NSTC journals, downloads, verification, and correction-email handling. The dashboard is therefore not just a view layer; it is the operational console for editing and exporting system data.

5. Authentication is a first-class subsystem. There are explicit routes for dashboard login, logout, verification, password reset request/confirm, and an auth callback under `app/auth/callback`. A `proxy.ts` file suggests request-time protection or routing guards, and `lib/auth.ts` centralizes auth logic. The presence of `auth-code-error` and `authorized-emails` implies controlled access based on email allowlists and verification codes rather than open self-signup.

6. The data layer is Supabase-backed. The repository contains `lib/supabase/client.ts` and `lib/supabase/server.ts` for client/server access patterns, plus a substantial `supabase/` directory with schema and maintenance SQL. That points to Supabase as the main persistence and storage boundary, with the app talking to it directly from route handlers and server components.

7. The `supabase/` folder is also part of the architecture, not just deployment trivia. It includes schema definition, storage policy scripts, schema sync scripts, and migration-like SQL for authorized emails, NSTC core journal records, and scholarship description fixes. This indicates the repo treats database structure and storage policies as versioned infrastructure alongside application code.

8. Email delivery is separated into its own utility layer under `lib/email/resend.ts`. In practice, this supports confirmation and correction workflows from scholarship-related APIs and probably dashboard-driven notifications. Resend is the external transactional email service in the system boundary.

9. There is a dedicated publications/import subsystem. `app/api/publications/fetch` exposes publication lookup, while `lib/doi.ts`, `lib/journal-index-service.ts`, `lib/journal-index-import.ts`, `lib/nstc-core-service.ts`, and `lib/nstc-core-import.ts` suggest ingestion and normalization pipelines for external publication metadata and journal index data. This is a backend enrichment layer rather than a user-facing feature.

10. The dashboard UI has several stateful presentation components: tables, tabs, detail views, program switchers, and admin panels under `app/dashboard/*`. These components consume API data and present operational workflows such as reviewing applications, switching scholarship programs, and displaying downloadable records.

11. Shared domain logic is concentrated in `lib/`. Files like `validation.ts`, `verification.ts`, `scholarship-settings.ts`, `scholarship-settings-server.ts`, `scholarship-form-options.ts`, `scholarship-language.ts`, `departments.ts`, and `dashboard-application-display.ts` hold the rules that multiple routes and components depend on. This is the main boundary where form rules, localization, allowed values, and display normalization are kept consistent across frontend and backend.

12. The component architecture is mostly built on a reusable UI kit under `components/ui/`, with a few higher-level app components such as `auth-button`, `language-toggle`, and `database-multi-select`. This indicates a component-driven frontend with a strong shared design system, likely used across both applicant-facing pages and the admin dashboard.

13. Operationally, the repo also includes Node scripts for dashboard account generation, password hashing, and password update generation. Those scripts reinforce that account/admin lifecycle is managed as part of the project rather than through an external admin console.

14. One important architectural note: the repository structure in the README references Prisma and older route locations, but the actual tree shows a Supabase-based implementation and a much broader dashboard/API surface. For diagramming, the current source tree should be treated as authoritative: Next.js App Router front end + API routes, Supabase persistence/storage, Resend email, and a protected admin dashboard.

Main entry points: [`app/api/dashboard/route.ts`](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/api/dashboard/route.ts) (Dashboard API), [`lib/supabase/server.ts`](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/lib/supabase/server.ts) (Supabase access), [`app/api/scholarships/route.ts`](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/api/scholarships/route.ts) (Scholarship API), [`app/layout.tsx`](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/layout.tsx) (Root layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Router"]
  node_root_layout["Root layout<br/>app shell<br/>[layout.tsx]"]
  node_home_page["Home page<br/>landing page<br/>[page.tsx]"]
  node_scholarship_selection["Selection UI<br/>client component"]
  node_scholarship_pages["Scholarship pages<br/>program pages"]
  node_auth_routes["Auth routes<br/>[route.ts]"]
  node_app_components["App components<br/>shared components<br/>[auth-button.tsx]"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_shell["Dashboard shell<br/>admin app<br/>[page.tsx]"]
  node_dashboard_views["Admin views<br/>dashboard components<br/>[dashboard-tabs.tsx]"]
  node_login_ui["Login form<br/>auth UI<br/>[login-form.tsx]"]
end

subgraph group_api["API Routes"]
  node_scholarship_api[("Scholarship API<br/>application routes<br/>[route.ts]")]
  node_dashboard_api[("Dashboard API<br/>admin routes<br/>[route.ts]")]
  node_publications_api[("Publications API<br/>lookup route<br/>[route.ts]")]
end

subgraph group_shared["Shared Logic"]
  node_auth_logic["Auth logic<br/>shared auth<br/>[auth.ts]"]
  node_domain_rules["Domain rules<br/>validation and config<br/>[validation.ts]"]
  node_display_mapping["Display mapping<br/>normalization"]
  node_publication_pipeline["Publication pipeline<br/>ingestion services"]
end

subgraph group_infra["Infra"]
  node_supabase_access[("Supabase access<br/>client/server data access<br/>[server.ts]")]
  node_supabase_schema[("Supabase schema<br/>sql schema<br/>[schema.sql]")]
  node_email_service["Email service<br/>transactional email<br/>[resend.ts]"]
end

subgraph group_ui["UI Kit"]
  node_shared_ui["UI kit<br/>component library<br/>[button.tsx]"]
end

node_root_layout -->|"renders"| node_home_page
node_root_layout -->|"hosts"| node_scholarship_pages
node_root_layout -->|"hosts"| node_dashboard_shell
node_home_page -->|"links to"| node_scholarship_selection
node_scholarship_selection -->|"drives"| node_scholarship_pages
node_scholarship_pages -->|"submits to"| node_scholarship_api
node_scholarship_api -->|"persists via"| node_supabase_access
node_scholarship_api -->|"sends"| node_email_service
node_scholarship_api -->|"validates with"| node_domain_rules
node_dashboard_shell -->|"composes"| node_dashboard_views
node_dashboard_shell -->|"routes through"| node_login_ui
node_dashboard_views -->|"loads from"| node_dashboard_api
node_dashboard_api -->|"guards with"| node_auth_logic
node_auth_routes -->|"delegates to"| node_auth_logic
node_auth_logic -->|"reads/writes"| node_supabase_access
node_dashboard_api -->|"queries"| node_supabase_access
node_dashboard_api -->|"sends"| node_email_service
node_dashboard_api -->|"formats with"| node_display_mapping
node_display_mapping -->|"depends on"| node_domain_rules
node_supabase_schema -->|"defines"| node_supabase_access
node_publication_pipeline -->|"serves"| node_publications_api
node_publication_pipeline -->|"hydrates from"| node_supabase_access
node_app_components -->|"builds on"| node_shared_ui
node_dashboard_views -->|"uses"| node_shared_ui
node_scholarship_pages -->|"uses"| node_domain_rules

click node_root_layout "https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/layout.tsx"
click node_home_page "https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/page.tsx"
click node_scholarship_selection "https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/scholarship-selection-client.tsx"
click node_scholarship_api "https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/api/scholarships/route.ts"
click node_dashboard_api "https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/api/dashboard/route.ts"
click node_publications_api "https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/api/publications/fetch/route.ts"
click node_auth_routes "https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/auth/callback/route.ts"
click node_dashboard_shell "https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/dashboard/page.tsx"
click node_dashboard_views "https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/dashboard/dashboard-tabs.tsx"
click node_login_ui "https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/dashboard/login/login-form.tsx"
click node_auth_logic "https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/lib/auth.ts"
click node_domain_rules "https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/lib/validation.ts"
click node_display_mapping "https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/lib/dashboard-application-display.ts"
click node_supabase_access "https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/lib/supabase/server.ts"
click node_supabase_schema "https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/supabase/schema.sql"
click node_email_service "https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/lib/email/resend.ts"
click node_publication_pipeline "https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/lib/journal-index-import.ts"
click node_shared_ui "https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/components/ui/button.tsx"
click node_app_components "https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/components/auth-button.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root_layout,node_home_page,node_scholarship_selection,node_scholarship_pages,node_auth_routes,node_app_components toneBlue
class node_dashboard_shell,node_dashboard_views,node_login_ui toneAmber
class node_scholarship_api,node_dashboard_api,node_publications_api toneMint
class node_auth_logic,node_domain_rules,node_display_mapping,node_publication_pipeline toneRose
class node_supabase_access,node_supabase_schema,node_email_service toneIndigo
class node_shared_ui toneTeal
```

## Components

### App Router

Public pages, route handlers, and route-scoped UI under Next.js App Router.

- [Root layout](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/layout.tsx): app shell · Global app shell and styles. · `app/layout.tsx`
- [Home page](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/page.tsx): landing page · Top-level entry page. · `app/page.tsx`
- [Selection UI](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/scholarship-selection-client.tsx): client component · Interactive scholarship chooser for applicants. · `app/scholarship-selection-client.tsx`
- **Scholarship pages**: program pages · Program-specific application pages for different scholarship tracks.
- [Auth routes](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/auth/callback/route.ts): auth routes · Login, logout, verification, reset, and callback handlers. · `app/auth/callback/route.ts`
- [App components](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/components/auth-button.tsx): shared components · Common app-level widgets such as auth, language, and multi-select controls. · `components/auth-button.tsx`

### Dashboard

Authenticated admin UI and its local presentation components.

- [Dashboard shell](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/dashboard/page.tsx): admin app · Main dashboard page composition and layout. · `app/dashboard/page.tsx`
- [Admin views](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/dashboard/dashboard-tabs.tsx): dashboard components · Tables, tabs, detail views, and program switching UI. · `app/dashboard/dashboard-tabs.tsx`
- [Login form](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/dashboard/login/login-form.tsx): auth UI · Dashboard sign-in form and login page. · `app/dashboard/login/login-form.tsx`

### API Routes

Server-side route handlers for scholarships, dashboard operations, publications, and auth.

- [Scholarship API](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/api/scholarships/route.ts): application routes · Submission, upload URL, and confirmation email endpoints. · `app/api/scholarships/route.ts`
- [Dashboard API](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/api/dashboard/route.ts): admin routes · Protected endpoints for accounts, programs, exports, verification, and corrections. · `app/api/dashboard/route.ts`
- [Publications API](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/app/api/publications/fetch/route.ts): lookup route · Publication fetch endpoint for metadata enrichment. · `app/api/publications/fetch/route.ts`

### Shared Logic

Cross-cutting domain rules, auth helpers, validation, and data access utilities.

- [Auth logic](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/lib/auth.ts): shared auth · Central auth and access-control logic. · `lib/auth.ts`
- [Domain rules](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/lib/validation.ts): validation and config · Validation, verification, scholarship settings, form options, and language rules. · `lib/validation.ts`
- [Display mapping](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/lib/dashboard-application-display.ts): normalization · Dashboard-facing application display and department mapping. · `lib/dashboard-application-display.ts`
- [Publication pipeline](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/lib/journal-index-import.ts): ingestion services · DOI, journal index, and NSTC core import/normalization services. · `lib/journal-index-import.ts`

### Infra

Supabase schema/migrations and external service integrations.

- [Supabase access](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/lib/supabase/server.ts): client/server data access · Client and server Supabase adapters. · `lib/supabase/server.ts`
- [Supabase schema](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/supabase/schema.sql): sql schema · Versioned database, storage, and policy scripts. · `supabase/schema.sql`
- [Email service](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/lib/email/resend.ts): transactional email · Resend integration for confirmation and correction workflows. · `lib/email/resend.ts`

### UI Kit

Reusable component library used across applicant and dashboard interfaces.

- [UI kit](https://github.com/coe-nthu/ipedu_scholarship_system/blob/main/components/ui/button.tsx): component library · Reusable interface primitives used throughout the app. · `components/ui/button.tsx`

## Connections

- Root layout → Home page: renders · The root shell surrounds the landing page and all nested routes.
- Root layout → Scholarship pages: hosts · App Router pages for applicant workflows live under the global layout.
- Root layout → Dashboard shell: hosts · Dashboard routes share the same application shell.
- Home page → Selection UI: links to · The landing experience leads applicants into scholarship selection.
- Selection UI → Scholarship pages: drives · Selection determines which scholarship program page the applicant enters.
- Scholarship pages → Scholarship API: submits to · Program pages send applications to scholarship submission endpoints.
- Scholarship API → Supabase access: persists via · Applications and related records are stored through Supabase access layers.
- Scholarship API → Email service: sends · Confirmation emails are triggered after successful submission.
- Scholarship API → Domain rules: validates with · Submission payloads are checked against shared scholarship rules.
- Dashboard shell → Admin views: composes · The dashboard page is built from tables, tabs, and detail panels.
- Dashboard shell → Login form: routes through · Authentication gates the admin experience through dedicated login UI.
- Admin views → Dashboard API: loads from · Admin screens consume protected dashboard endpoints.
- Dashboard API → Auth logic: guards with · Dashboard endpoints rely on centralized auth and allowlist logic.
- Auth routes → Auth logic: delegates to · Login, verification, reset, and callback flows use shared auth behavior.
- Auth logic → Supabase access: reads/writes · Auth state and user records are coordinated through Supabase.
- Dashboard API → Supabase access: queries · Administrative data operations use the shared Supabase adapters.
- Dashboard API → Email service: sends · Password reset and correction workflows can emit transactional email.
- Dashboard API → Display mapping: formats with · Dashboard responses are normalized for admin presentation.
- Display mapping → Domain rules: depends on · Presentation normalization follows shared domain settings and validation rules.
- Supabase schema → Supabase access: defines · Schema and policies define the persistence boundary used by the app.
- Publication pipeline → Publications API: serves · Publication fetch exposes the enrichment pipeline to callers.
- Publication pipeline → Supabase access: hydrates from · Imported journal and publication data is stored or read through Supabase.
- App components → UI kit: builds on · Higher-level app widgets are composed from the shared UI kit.
- Admin views → UI kit: uses · Admin interfaces are assembled from reusable UI primitives.
- Scholarship pages → Domain rules: uses · Applicant forms share settings, validation, and language rules.