334 lines
19 KiB
Markdown
334 lines
19 KiB
Markdown
# Semantic Analysis Report — IoT Standards Lab Landing Page Prototype
|
||
|
||
This report provides a structured, semantic read-only analysis of the reference prototype codebase for the Kyungpook National University IoT Standards Lab. The workspace contains approximately 2,605 lines of code across 25 files using Next.js 14, React 18, TypeScript 5, and Tailwind CSS 3.
|
||
|
||
---
|
||
|
||
## 1. Modules and Responsibilities
|
||
|
||
This project is structured as a standard Next.js 14 App Router codebase. The responsibilities are clearly divided between page routing structures and reusable UI components.
|
||
|
||
* `app/`
|
||
* **Purpose**: Owns the application routing, page structures, global layouts, metadata configurations, and global styles. It manages the core shell of the application but delegates UI component instantiation to the shared `components/` directory.
|
||
* **Key Files**:
|
||
* `app/layout.tsx`: Root layout configuration. Imports next/font Google Serifs/Sans, sets up base metadata, and wraps pages in standard header/footer.
|
||
* `app/globals.css`: Contains CSS variable mappings matching design system tokens, grain background effects, custom typography class layers, and scroll-reveal CSS transitions.
|
||
* `app/intro/`
|
||
* **Purpose**: Owns the primary landing page (root route `/` or `/intro`), introducing the lab's core identity, mission, statistical counters, and two research thrusts.
|
||
* **Key Files**:
|
||
* `app/intro/page.tsx`: Orchestrates the cover page layouts, mission quotes, and research thrust cards.
|
||
* `app/intro/_components/`
|
||
* **Purpose**: Private subdirectory for intro-specific UI components. It does not share these components with other routes.
|
||
* **Key Files**:
|
||
* `app/intro/_components/HeroComposition.tsx`: Custom inline SVG render of an abstract mesh (representing MCM) and flow streams (representing QUIC) with native CSS animations.
|
||
* `app/lectures/`
|
||
* **Purpose**: Owns the route `/lectures` displaying academic coursework and lectures offered by the lab director.
|
||
* **Key Files**:
|
||
* `app/lectures/page.tsx`: Renders course articles with details on codes, target levels, and descriptions.
|
||
* `app/members/`
|
||
* **Purpose**: Owns the route `/members` showing the lab members, beginning with the PI and grouping student researchers.
|
||
* **Key Files**:
|
||
* `app/members/page.tsx`: Maps advisors, Ph.D. students, M.S. students, and undergraduate researchers.
|
||
* `app/publications/`
|
||
* **Purpose**: Owns the route `/publications` displaying selected publications and output statistics.
|
||
* **Key Files**:
|
||
* `app/publications/page.tsx`: Houses publication data (Journals, Conferences) mapped in a list layout.
|
||
* `app/standardization/`
|
||
* **Purpose**: Owns the route `/standardization` highlighting contributions made to various international standards bodies.
|
||
* **Key Files**:
|
||
* `app/standardization/page.tsx`: Groups standardization details per organization (oneM2M, W3C, IETF, OMA).
|
||
* `components/`
|
||
* **Purpose**: Owns all shared, reusable presentation and interaction components. It holds no business logic and relies on configurable props to customize content.
|
||
* **Key Files**:
|
||
* `components/Header.tsx`: Responsive navigation bar with mobile menu toggles.
|
||
* `components/Footer.tsx`: Site footer including address, email, and internal site index.
|
||
* `components/PageHeader.tsx`: Reusable route banner supporting dual-language headers.
|
||
* `components/SectionLabel.tsx`: corner-aligned section label ("01 / 05") mimicking magazine spreads.
|
||
* `components/Reveal.tsx`: Motion wrapper triggering transition classes on scroll.
|
||
* `components/Counter.tsx`: Client-side tick-up animation for figures.
|
||
* `components/Marquee.tsx`: Endless horizontally running keyword ticker.
|
||
* `docs/`
|
||
* **Purpose**: Owns documentation on the design system layout, color tokens, typography scales, and motion specifications.
|
||
* **Key Files**:
|
||
* `docs/DESIGN.md`: The canonical specification guide for the editorial magazine system ("Issue 01").
|
||
|
||
---
|
||
|
||
## 2. Public API Surface
|
||
|
||
### (a) Shared Components (components/)
|
||
|
||
* `Counter` (default export) in `components/Counter.tsx:11`
|
||
* **Props Shape**:
|
||
```typescript
|
||
{
|
||
value: number;
|
||
duration?: number;
|
||
prefix?: string;
|
||
suffix?: string;
|
||
className?: string;
|
||
}
|
||
```
|
||
* **Consumers**:
|
||
* `app/intro/page.tsx:5` (line figure metrics)
|
||
* `app/members/page.tsx:5` (headcount metrics)
|
||
* `app/publications/page.tsx:5` (publication count metrics)
|
||
* `app/standardization/page.tsx:5` (contribution metrics)
|
||
* `Footer` (default export) in `components/Footer.tsx:13`
|
||
* **Props Shape**: `{}` (takes no props)
|
||
* **Consumers**:
|
||
* `app/layout.tsx:5` (global page shell)
|
||
* `Header` (default export) in `components/Header.tsx:16`
|
||
* **Props Shape**: `{}` (takes no props)
|
||
* **Consumers**:
|
||
* `app/layout.tsx:4` (global page shell)
|
||
* `Marquee` (default export) in `components/Marquee.tsx:9`
|
||
* **Props Shape**:
|
||
```typescript
|
||
{
|
||
items: string[];
|
||
reverse?: boolean;
|
||
className?: string;
|
||
}
|
||
```
|
||
* **Consumers**:
|
||
* `app/intro/page.tsx:4` (keywords banner)
|
||
* `components/Footer.tsx:2` (colophon running ticker)
|
||
* `app/publications/page.tsx:6` (venues ticker)
|
||
* `app/standardization/page.tsx:6` (standards bodies ticker)
|
||
* `PageHeader` (default export) in `components/PageHeader.tsx:10`
|
||
* **Props Shape**:
|
||
```typescript
|
||
{
|
||
ko: string;
|
||
en: string;
|
||
display?: string;
|
||
description?: string;
|
||
index: number;
|
||
}
|
||
```
|
||
* **Consumers**:
|
||
* `app/lectures/page.tsx:2` (page introduction banner)
|
||
* `app/members/page.tsx:2` (page introduction banner)
|
||
* `app/publications/page.tsx:2` (page introduction banner)
|
||
* `app/standardization/page.tsx:2` (page introduction banner)
|
||
* `Reveal` (default export) in `components/Reveal.tsx:15`
|
||
* **Props Shape**:
|
||
```typescript
|
||
{
|
||
children: ReactNode;
|
||
variant?: "up" | "left" | "right" | "scale";
|
||
delay?: number;
|
||
as?: ElementType;
|
||
className?: string;
|
||
}
|
||
```
|
||
* **Consumers**:
|
||
* `app/intro/page.tsx:3` (scroll stagger containers)
|
||
* `app/lectures/page.tsx:3` (scroll stagger containers)
|
||
* `app/members/page.tsx:3` (scroll stagger containers)
|
||
* `app/publications/page.tsx:3` (scroll stagger containers)
|
||
* `app/standardization/page.tsx:3` (scroll stagger containers)
|
||
* `components/PageHeader.tsx:2` (in-header transitions)
|
||
* `SectionLabel` (default export) in `components/SectionLabel.tsx:7`
|
||
* **Props Shape**:
|
||
```typescript
|
||
{
|
||
index: number;
|
||
total?: number;
|
||
label: string;
|
||
className?: string;
|
||
}
|
||
```
|
||
* **Consumers**:
|
||
* `app/intro/page.tsx:6` (layout sub-numbering)
|
||
* `app/lectures/page.tsx:4` (layout sub-numbering)
|
||
* `app/members/page.tsx:4` (layout sub-numbering)
|
||
* `app/publications/page.tsx:4` (layout sub-numbering)
|
||
* `app/standardization/page.tsx:4` (layout sub-numbering)
|
||
* `components/PageHeader.tsx:1` (header numbering tag)
|
||
|
||
### (b) Page-level Components (app/)
|
||
|
||
* `RootLayout` (default export) in `app/layout.tsx:44`
|
||
* **Props Shape**: `{ children: React.ReactNode; }`
|
||
* **Consumers**: Entry layout shell for the Next.js router.
|
||
* `metadata` (named export) in `app/layout.tsx:35`
|
||
* **Props Shape**: `Metadata` (Next.js config object)
|
||
* **Consumers**: Resolved internally by Next.js for page metadata headers.
|
||
* `IntroPage` (default export) in `app/intro/page.tsx:73`
|
||
* **Props Shape**: `{}` (takes no props)
|
||
* **Consumers**: Next.js App Router path resolver.
|
||
* `metadata` (named export) in `app/intro/page.tsx:9`
|
||
* **Props Shape**: `Metadata`
|
||
* **Consumers**: Resolved internally by Next.js.
|
||
* `LecturesPage` (default export) in `app/lectures/page.tsx:45`
|
||
* **Props Shape**: `{}` (takes no props)
|
||
* **Consumers**: Next.js App Router path resolver.
|
||
* `metadata` (named export) in `app/lectures/page.tsx:6`
|
||
* **Props Shape**: `Metadata`
|
||
* **Consumers**: Resolved internally by Next.js.
|
||
* `MembersPage` (default export) in `app/members/page.tsx:65`
|
||
* **Props Shape**: `{}` (takes no props)
|
||
* **Consumers**: Next.js App Router path resolver.
|
||
* `metadata` (named export) in `app/members/page.tsx:7`
|
||
* **Props Shape**: `Metadata`
|
||
* **Consumers**: Resolved internally by Next.js.
|
||
* `PublicationsPage` (default export) in `app/publications/page.tsx:84`
|
||
* **Props Shape**: `{}` (takes no props)
|
||
* **Consumers**: Next.js App Router path resolver.
|
||
* `metadata` (named export) in `app/publications/page.tsx:8`
|
||
* **Props Shape**: `Metadata`
|
||
* **Consumers**: Resolved internally by Next.js.
|
||
* `StandardizationPage` (default export) in `app/standardization/page.tsx:88`
|
||
* **Props Shape**: `{}` (takes no props)
|
||
* **Consumers**: Next.js App Router path resolver.
|
||
* `metadata` (named export) in `app/standardization/page.tsx:8`
|
||
* **Props Shape**: `Metadata`
|
||
* **Consumers**: Resolved internally by Next.js.
|
||
|
||
### (c) Private Components (app/<route>/_components/)
|
||
|
||
* `HeroComposition` (default export) in `app/intro/_components/HeroComposition.tsx:9`
|
||
* **Props Shape**: `{ className?: string; }`
|
||
* **Consumers**:
|
||
* `app/intro/page.tsx:7` (embedded inline SVG cover graphic)
|
||
|
||
### (d) Utilities/Hooks
|
||
|
||
* **None**. No utility files or custom hooks exist in the codebase. All custom scrolling or counter timing functions are written directly inline within `useEffect` wrappers of the respective UI components.
|
||
|
||
---
|
||
|
||
## 3. Test Coverage Footprint
|
||
|
||
* **Test Files Found**: A workspace-wide search for patterns such as `*.test.*`, `*.spec.*`, `__tests__/`, `vitest.config*`, `jest.config*`, `playwright.config*`, and `cypress/` returned **zero files**. There is no testing framework configured, nor are there any test scripts defined in `package.json`.
|
||
* **CI Configuration**: No CI configurations (e.g. `.github/workflows` or GitLab CI configuration files) exist in the workspace.
|
||
* **Coverage Matrix**:
|
||
|
||
| Component / Route | Coverage Status | Evidence / Notes |
|
||
| --- | --- | --- |
|
||
| `components/Counter.tsx` | **UNTESTED** | No test file exists; contains requestAnimationFrame loops requiring mock timers. |
|
||
| `components/Footer.tsx` | **UNTESTED** | No test file exists; pure static HTML render. |
|
||
| `components/Header.tsx` | **UNTESTED** | No test file exists; houses mobile menu toggling state. |
|
||
| `components/Marquee.tsx` | **UNTESTED** | No test file exists; renders static marquee track loops. |
|
||
| `components/PageHeader.tsx` | **UNTESTED** | No test file exists; renders standard dual headings. |
|
||
| `components/Reveal.tsx` | **UNTESTED** | No test file exists; relies on IntersectionObserver hooks. |
|
||
| `components/SectionLabel.tsx` | **UNTESTED** | No test file exists; simple presentation decorator. |
|
||
| `app/layout.tsx` | **UNTESTED** | No test file exists; handles font loading and root HTML. |
|
||
| `app/intro/page.tsx` | **UNTESTED** | No test file exists; orchestrates landing sections. |
|
||
| `app/intro/_components/HeroComposition.tsx` | **UNTESTED** | No test file exists; renders raw SVG frames and paths. |
|
||
| `app/lectures/page.tsx` | **UNTESTED** | No test file exists; presentation routing. |
|
||
| `app/members/page.tsx` | **UNTESTED** | No test file exists; presentation routing. |
|
||
| `app/publications/page.tsx` | **UNTESTED** | No test file exists; presentation routing. |
|
||
| `app/standardization/page.tsx` | **UNTESTED** | No test file exists; presentation routing. |
|
||
|
||
* **Top 3 Testing Gaps**:
|
||
1. **`components/Reveal.tsx`**: Since it acts as a layout wrapper for almost all elements across all pages, any regression in the IntersectionObserver attachment could render all pages entirely invisible (stuck at opacity 0).
|
||
2. **`components/Counter.tsx`**: Uses `requestAnimationFrame` and an active observer, which can cause frame stuttering or rendering failures on outdated browsers if not properly tested/mocked.
|
||
3. **`components/Header.tsx`**: Manages the mobile view menu drawer state. Failure here blocks mobile navigation.
|
||
|
||
---
|
||
|
||
## 4. Documentation Presence
|
||
|
||
* **`README.md`**: Provides a clear introduction mapping the project's purpose as a reference prototype. It includes a lab overview, technology stack, directory layout, routing map table, design system overview, and customization hooks outlining where to modify styles, colors, and static data variables.
|
||
* *First 20 lines quote*:
|
||
```markdown
|
||
# 사물인터넷 표준 연구실 랜딩 페이지 (Reference Prototype)
|
||
|
||
경북대학교 컴퓨터학부 **사물인터넷 표준 연구실(IoT Standards Lab)** 의 랜딩 페이지
|
||
**참고용 프로토타입**입니다. 프로덕션 배포용이 아니라, 구조와 디자인을 참고해
|
||
실제 콘텐츠로 교체하기 위한 레퍼런스 구현입니다. 모든 인물·논문·표준 기여 내역은
|
||
예시(placeholder)이므로 실제 정보로 바꿔서 사용하세요.
|
||
|
||
## 연구실 소개 (Lab Context)
|
||
|
||
본 연구실은 사물인터넷 국제 표준을 기반으로 **(a) 메타버스 상호운용성(MCM Project)**
|
||
과 **(b) QUIC 기반 멀티에이전트 오케스트레이션 아키텍처 및 통신 인터페이스 설계**
|
||
두 가지 축을 연구합니다.
|
||
|
||
## 기술 스택 (Tech Stack)
|
||
|
||
- **Next.js 14+** (App Router)
|
||
- **TypeScript**
|
||
- **Tailwind CSS**
|
||
```
|
||
* **`PROMPT.md`**: Confirming this is a **developer-facing prompt session history log** rather than user documentation. It logs the exact prompt briefs, session USD costs, and incremental generation patterns used when the AI created the repository.
|
||
* **`docs/` Directory**:
|
||
* `docs/DESIGN.md`: The **canonical design system specification** detailing color tokens, typography scales, motion principles, and reuse rules for shared elements under "Issue 01".
|
||
* **JSDoc Coverage**:
|
||
* **5 out of 7 (71.4%)** exported components in `components/` include structured JSDoc descriptions.
|
||
* *Sample 1 (with JSDoc)*: `components/Counter.tsx` lines 5–10:
|
||
```typescript
|
||
/**
|
||
* Number that ticks up from 0 → `value` when scrolled into view.
|
||
* Uses requestAnimationFrame only (no animation library).
|
||
*
|
||
* CUSTOMIZATION HOOK — CONTENT: value / prefix / suffix.
|
||
*/
|
||
```
|
||
* *Sample 2 (with JSDoc)*: `components/Reveal.tsx` lines 7–14:
|
||
```typescript
|
||
/**
|
||
* Scroll-triggered reveal. Uses a single IntersectionObserver (no deps).
|
||
* Pairs with the `.reveal` / `.is-visible` rules in globals.css.
|
||
*
|
||
* CUSTOMIZATION HOOK — MOTION:
|
||
* variant → direction of entrance
|
||
* delay → stagger (ms), applied as transition-delay
|
||
*/
|
||
```
|
||
* *Sample 3 (without JSDoc)*: `components/Footer.tsx` line 13:
|
||
```typescript
|
||
export default function Footer() {
|
||
```
|
||
* *Sample 4 (without JSDoc)*: `components/Header.tsx` line 16:
|
||
```typescript
|
||
export default function Header() {
|
||
```
|
||
* **Documentation Gaps**:
|
||
1. **No Data Flow & API integration guidance**: Lacks documentation explaining how to decouple the hardcoded static variables into remote databases, markdown files, or headless CMS feeds.
|
||
2. **No local runtime guidelines**: Does not state supported Node.js version ranges (e.g., node 18/20 LTS) or lockfile rules to prevent dependency drift when a developer sets up local development.
|
||
3. **No coding standard/linting rules documentation**: Missing details on stylistic constraints (e.g. Prettier or specific TypeScript guidelines) to maintain editorial design conventions.
|
||
|
||
---
|
||
|
||
## 5. Code Smells
|
||
|
||
* **Duplication**:
|
||
* *JSX Structure*: The **Figures Counter Section** pattern is copy-pasted across 4 files. They use the same layout class structure:
|
||
```tsx
|
||
<section className="border-b border-ink">
|
||
<div className="container-content grid gap-px bg-line sm:grid-cols-3">
|
||
```
|
||
And they loop over a list mapping to `<Counter>`:
|
||
* `app/intro/page.tsx` (lines 145–161)
|
||
* `app/members/page.tsx` (lines 75–87)
|
||
* `app/publications/page.tsx` (lines 103–115)
|
||
* `app/standardization/page.tsx` (lines 106–118)
|
||
* *Marquee Band Sections*: Very similar wrapper layouts enclosing `<Marquee>` components:
|
||
* `app/intro/page.tsx` (lines 136–142)
|
||
* `app/publications/page.tsx` (lines 94–101)
|
||
* `app/standardization/page.tsx` (lines 98–104)
|
||
* *Static Data Shapes*: Static arrays are defined at the top of each page file, coupling presentation and routing code directly with source content.
|
||
* **Dead Code**:
|
||
* *Unused Design Tokens*: The `brand` and `accent` configurations in `tailwind.config.ts` (lines 48–53) are deprecated aliases marked as "back-compat" to avoid breaking stray classes, but are not actively referenced anywhere in the source files.
|
||
* **Oversized Files**:
|
||
* `app/intro/page.tsx` is **288 lines long**. This size is partly justified as it acts as the primary landing page with multiple complex layout structures. However, it also embeds multiple large static arrays (e.g. `thrusts`, `figures`, `keywords`, `focusAreas`) directly in the file. Separating these datasets into a localized content file would reduce complexity.
|
||
* **Prop Drilling**:
|
||
* None identified. The components are flat and presentation-only, and do not pass state down multiple layers.
|
||
* **Other Smells**:
|
||
* TypeScript rules are strictly followed: there is no usage of `any` types or assertions, and no non-null (`!`) assertion bypasses.
|
||
* Looping `key` props are correctly defined and mapped across all loops in the project.
|
||
|
||
---
|
||
|
||
## 6. Summary
|
||
|
||
This codebase functions as a high-fidelity reference prototype and layout scaffold for a university research laboratory portal. The primary strength of the project is its exceptional editorial visual identity ("Issue 01") and its clean, type-safe implementation that respects accessibility parameters (such as `prefers-reduced-motion`). The top 3 risks/gaps identified are:
|
||
|
||
1. **Statically Coupled Content**: Page data (like membership lists, publications, and standardized contributions) is hardcoded directly inside page routes, making updates labor-intensive and error-prone for non-developers.
|
||
2. **Lack of Automated Verification**: The complete absence of testing tools, linting workflows, or CI pipelines poses a risk of visual regression or runtime failures during layout refactoring.
|
||
3. **No decoupled content or asset structure**: Static SVGs (like `HeroComposition`) are locked in hardcoded coordinates, preventing easy swap-outs of layout designs by non-designers.
|