lab/landing_page
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f3f53c131895792056a65de25c9003e8b3952792
landing_page/refer_landing_page/.kanban-final-report.md
T

16 KiB
Raw Blame History

IoT Standards Lab Landing Page — Final Project Analysis

Workspace: /home/godopu16/PuKi/lab/landing_page/refer_landing_page Project: iot-standards-lab-landing v0.1.0 (private) Produced as the synthesis deliverable for kanban task t_d70b2c9e. Sources: .kanban-inventory.json (t_5662ba34), .kanban-stack-profile.md (t_239791d2), .kanban-semantic-analysis.md (t_a62d94ab).

1. What this project is

This repo is a reference prototype landing page for the 경북대학교 컴퓨터학부 사물인터넷 표준 연구실 (KNU CS IoT Standards Lab) — a small, self-contained marketing site (not a deployed product) intended to be cloned and filled in with the lab's real content. It is structured as a single-page-family academic portal: a hero/intro route, plus four content routes (lectures, members, publications, standardization), all wrapped in a hand-rolled editorial design system dubbed "Issue 01" — a magazine-spread aesthetic with serif/sans pairing, grain backgrounds, scroll-reveal motion, and running marquee tickers. All listed people, papers, and standards contributions are placeholders to be swapped for real data; the deliverable is the layout, design system, and motion language, not the content. Roughly 2,605 LOC across 25 source files; small enough to read end-to-end in an afternoon.

2. Tech stack

Layer Pin Notes
Framework next@14.2.5 (exact) App Router; reactStrictMode: true; no image domains / redirects / experimental flags
Language TypeScript 5.5 (installed 5.9.3) strict: true, moduleResolution: "bundler", path alias @/*
UI runtime react@18.3.1 + react-dom@18.3.1 React 18, not 19 — locked to Next 14 line
Styling tailwindcss@3.4.6 + postcss@8.4 + autoprefixer@10.4 Custom theme in tailwind.config.ts (114 lines)
Lint eslint@8.57 + eslint-config-next@14.2.5 (exact, matches Next) No .eslintrc*, no Prettier
Fonts next/font (Google Serif + Sans exposed as CSS vars) No external font loader dep
Package manager npm 10.9.7, lockfile v3 Single package-lock.json (215 KB); no pnpm/yarn/bun
Runtime Node 22.22.2 (host) No engines field declared

Scripts (4, the entire quality-gate surface): npm run dev · npm run build · npm start · npm run lint.

Not present: no Docker, no .env/env vars, no CI, no test runner, no formatter, no UI lib (no shadcn/Radix/MUI), no icon set, no analytics, no CMS client, no image CDN, no motion library (motion is hand-rolled via IntersectionObserver + CSS).

Security posture: npm audit reports 8 advisories, 1 critical, 6 high, 1 moderate. 21 of those resolve by a single-line patch — npm install next@14.2.35 (same major, fixes cache poisoning, Server Components DoS, middleware SSRF, PostCSS XSS, etc.). Transitive glob and minimatch advisories are dev-time only and not runtime risks for this app.

3. Architecture and structure

Tree (top-level)

/home/godopu16/PuKi/lab/landing_page/refer_landing_page
├── app/                       ← Next.js App Router entrypoint
│   ├── layout.tsx             ← Root layout: Header + Footer + font vars
│   ├── globals.css            ← CSS vars, grain bg, reveal transitions
│   ├── intro/                 ← /          (root landing)
│   │   ├── page.tsx           ←   287 lines, uses HeroComposition
│   │   └── _components/
│   │       └── HeroComposition.tsx  ← private inline-SVG cover graphic
│   ├── lectures/page.tsx      ← /lectures    102 lines
│   ├── members/page.tsx       ← /members     174 lines
│   ├── publications/page.tsx  ← /publications 168 lines
│   └── standardization/page.tsx ← /standardization 169 lines
├── components/                ← 7 shared, reusable components
│   ├── Header.tsx             ← nav + mobile menu
│   ├── Footer.tsx             ← address/email + Marquee colophon
│   ├── PageHeader.tsx         ← dual-language route banner
│   ├── SectionLabel.tsx       ← "01 / 05" corner labels
│   ├── Counter.tsx            ← tick-up figure animation
│   ├── Marquee.tsx            ← endless running ticker
│   └── Reveal.tsx             ← IntersectionObserver scroll reveal
├── docs/DESIGN.md             ← 332 lines — design system spec
├── PROMPT.md                  ← 249 lines — original generation brief
├── README.md                  ← 104 lines — project overview
├── package.json / package-lock.json (215 KB)
├── tsconfig.json (22) / next.config.js (6) / next-env.d.ts
├── tailwind.config.ts (114)   ← canonical design tokens
├── postcss.config.js (6)
├── .gitignore (27)
└── .kanban-*.{json,md}        ← upstream task artifacts (not project content)

Routing map (Next.js App Router)

Path File Lines Notes
/ app/intro/page.tsx 287 Embeds static thrusts, figures, keywords, focusAreas arrays
/lectures app/lectures/page.tsx 102 Course list
/members app/members/page.tsx 174 PI + PhD + MS + UG groupings
/publications app/publications/page.tsx 168 Journals + Conferences
/standardization app/standardization/page.tsx 169 oneM2M, W3C, IETF, OMA groups

Shared component fan-out

Component Used in (routes / other components) Public prop shape
Header app/layout.tsx {}
Footer app/layout.tsx {}
Counter intro, members, publications, standardization { value, duration?, prefix?, suffix?, className? }
Marquee intro, publications, standardization, Footer { items: string[], reverse?, className? }
PageHeader lectures, members, publications, standardization { ko, en, display?, description?, index }
Reveal intro, lectures, members, publications, standardization, PageHeader { children, variant?: 'up'|'left'|'right'|'scale', delay?, as?, className? }
SectionLabel intro, lectures, members, publications, standardization, PageHeader { index, total?, label, className? }

5 of the 7 (71%) shared components carry JSDoc blocks; Header and Footer do not.

Module responsibilities (one-line summary)

  • app/ — routing, metadata, global shell; page-level orchestration only, no business logic.
  • app/intro/_components/ — private assets scoped to one route (HeroComposition SVG).
  • components/ — presentation primitives, prop-driven, zero business logic.
  • docs/DESIGN.md — canonical design-token spec (the "Issue 01" system).
  • tailwind.config.ts — machine-readable counterpart to docs/DESIGN.md; treat it as the source of truth at the build layer.

4. Strengths and risks

Strengths

  1. Internally consistent stack. Next 14.2.5, React 18.3, Tailwind 3.4, TS 5.5, ESLint 8 + eslint-config-next pinned to Next's exact version. No mixed majors, no version skew between next and eslint-config-next. The dep tree is the smallest viable Next 14 surface — package-lock.json is only 215 KB, no obvious bloat.
  2. Strict TypeScript hygiene. Zero any types, zero non-null (!) assertions, correct key props on every loop. tsconfig.json is the canonical strict-mode setup (strict, noEmit, incremental, isolatedModules, moduleResolution: "bundler").
  3. Design system is well-documented and decoupled from data. docs/DESIGN.md (332 lines) + tailwind.config.ts (114 lines) are the canonical design sources; component JSDoc blocks (5/7) call out "CUSTOMIZATION HOOK — CONTENT/MOTION" seams. A non-developer touching content can find the right file via the README's customization hooks section.
  4. No external runtime dependencies beyond Next itself. No motion lib, no icon set, no UI kit, no analytics, no CMS. Reveal motion uses a hand-rolled IntersectionObserver; counter uses requestAnimationFrame only. The runtime is small and inspectable.
  5. A11y-aware motion. Reveal respects prefers-reduced-motion; semantic HTML throughout (no <div>-as-button patterns).
  6. Trivial security remediation available. A single npm install next@14.2.35 clears 21 published advisories (1 critical, 6 high, 1 moderate) — no major jump, no React change, no behavior change.

Risks and gaps

  1. 0% test coverage. No test framework, no *.test.* / *.spec.* files, no test script in package.json, no CI. All 14 components/routes are UNTESTED. The highest-leverage gaps:
    • Reveal — wraps most page content; a broken IntersectionObserver attachment would render pages invisible (stuck at opacity 0).
    • Counter — uses requestAnimationFrame; regressions could leak rAF loops.
    • Header — owns mobile menu state; a regression blocks mobile navigation.
  2. Statically coupled content. Member rosters, publication lists, lecture catalogs, and standards contributions live as hardcoded TS arrays inside the page files (app/intro/page.tsx is 287 lines partly because it embeds thrusts, figures, keywords, focusAreas directly). Non-developers cannot update content without a TS edit. The README's customization hooks point at the code locations but offer no path to a CMS, markdown, or remote data source.
  3. 21 outstanding Next.js security advisories (1 critical, 6 high, 1 moderate). All fixed by bumping next to 14.2.35; none are runtime-blocked today, but a security review or production deploy would fail.
  4. Code duplication. The "Figures Counter Section" pattern (3-col grid of <Counter> cells) is copy-pasted across 4 page files (intro:145-161, members:75-87, publications:103-115, standardization:106-118). A <FiguresBand> shared component would collapse ~60 lines of repetition. The marquee band wrapper is similarly repeated in 3 places.
  5. Dead design tokens. brand and accent palettes in tailwind.config.ts:48-53 are marked as back-compat aliases and have no consumers. They bloat the theme and may mislead future contributors.
  6. Hardcoded private SVG. HeroComposition.tsx embeds mesh/flow coordinates inline — no way for a designer to swap the cover graphic without editing TSX.
  7. No CI, no formatter, no env var convention, no Node version pin in engines. A new contributor on a different Node major could see different behavior; PRs have no automated lint/typecheck gate.
  8. Documentation gaps. README is strong on design system but lacks: (a) supported Node/npm versions, (b) content-update workflow, (c) deploy story, (d) coding-standard / lint rules documentation.
  9. No src/pages separation, no cmd dir, no monorepo markers. This is fine for a single-app reference but means there is no scaffold for growth (e.g. a future /admin route or a separate landing for a sister project would have to invent conventions).
  10. Major-version lag (informational, not blocking). Next 16 / React 19 / Tailwind 4 / TS 6 / ESLint 10 are all available. Each is a planned migration, not a security issue — but anyone picking up the project in 2027 will need a multi-week upgrade pass.

5. Suggested next steps (prioritized)

P0 — Do now (low effort, high value)

  1. Patch Next.js security advisories. npm install next@14.2.35 — single-line, no behavior change, clears 21 advisories. Run npm audit after to confirm. (~5 min)
  2. Extract the duplicated Figures Counter Section into a shared <FiguresBand items={...} /> component. Touches 4 page files; collapses ~60 lines of duplication. (~30 min)
  3. Remove dead brand / accent tokens from tailwind.config.ts:48-53. (~5 min)

P1 — Do before any production deploy or public handoff

  1. Add an engines field to package.json ("node": ">=20") and document supported versions in README.md. Prevents the "works on my machine" drift.
  2. Add a minimal test setup — Vitest + React Testing Library is the lowest-friction choice for a Next 14 + TS + no-CI codebase. Start with Reveal, Counter, and Header (the three highest-leverage gaps from §3). (~half-day)
  3. Decouple content from page files. Even a minimal pass — move the figures, keywords, thrusts, focusAreas arrays from app/intro/page.tsx into app/intro/_content.ts — would make future CMS migration a 1-file change instead of a 4-file one. Same treatment for members, publications, lectures, standardization. (~2 hours)
  4. Add a CI workflow (GitHub Actions) running npm run lint, npm run build, and (once added) npm test. (~1 hour)

P2 — Quality and developer-experience

  1. Externalize the hero SVG. Move HeroComposition coordinates into a JSON or TS data file so designers can iterate without editing TSX. (~2 hours)
  2. Add Prettier with a project-wide config; wire it into the lint CI check. The design system is editorial — typographic drift is a real risk without a formatter. (~1 hour)
  3. Fill the documentation gaps in README.md: Node version, content-update workflow, deploy story, lint/style rules. (~2 hours)

P3 — Planned migrations (do not bundle with security work)

  1. Next 16 + React 19 + Tailwind 4 upgrade. All three are major-version jumps; budget a dedicated sprint. The Tailwind v3 → v4 jump is the largest unknown (config format change) — prototype it in a branch first.
  2. TypeScript 6 and ESLint 10 (flat config) are mostly mechanical and can ride along with the Next 16 migration.

Anti-recommendations (do not do)

  • Do not npm audit fix --force — that would jump to Next 16 + React 19 in one move, bundling a security patch with a major migration. The single-line next@14.2.35 patch is the correct shape.
  • Do not turn this into a CMS-backed app before extracting the content arrays; the current shape is the right baseline for a reference prototype, but only if the baseline is clean.
  • Do not introduce a UI library (shadcn, Radix) or motion library (framer-motion) for the sake of modernization — the hand-rolled motion is a feature, not a gap, and a UI lib would clash with the editorial design system.

6. Appendix — Source artifacts

This report is a synthesis of three upstream kanban tasks. Each was a stand-alone analysis with its own file:line citations and acceptance criteria.

Task Title Artifact Role
t_5662ba34 Inventory project layout and file structure .kanban-inventory.json Structural inventory: 25 source files, 5 routes, 7 components, ~2,605 LOC; no monorepo markers; no test/format/CI/Docker/env markers.
t_239791d2 Analyze dependencies, build config, and runtime stack .kanban-stack-profile.md Stack profile: dep breakdown (3 runtime + 10 dev), scripts, configs, security audit (8 advisories, 1 critical), version-compatibility sketch.
t_a62d94ab Survey code semantics, tests, and documentation .kanban-semantic-analysis.md Semantic read: module map, public API surface with prop shapes and consumers, test coverage matrix (14/14 UNTESTED), documentation audit, code smells.

Reading order for a human reviewer: if you only have 10 minutes, read §1 + §4 (Strengths and risks) + §5 P0 items. If you have 30 minutes, add the three source artifacts — they cite specific files and line ranges throughout.

Not part of the project (do not treat as source of truth): .antigravity-session.md is a runtime artifact from the upstream t_c6396592 task; .kanban-*.{json,md} files are this kanban session's analysis outputs and are not project documentation.

Reference in New Issue View Git Blame Copy Permalink