Point — Dev Knowledge Radar (Skill Graph)

Персональный инструмент управления инженерными знаниями: AI генерирует глобальный граф навыков, пользователь формирует свой срез, система считает метрики и строит план обучения/roadmap.

Статус: репозиторий содержит базовый скелет Next.js приложения; продуктовые требования, архитектурные заметки и UI-вайрфреймы лежат в docs/.

---

1. Product Overview

Что это

• Knowledge/Skill Graph + Tech Radar + Learning Roadmap в одном интерфейсе.
• Ориентация на одного пользователя (MVP без auth), с потенциалом эволюции в шаринг/командный режим.

Цели

• Визуализировать ландшафт технологий/навыков как интерактивный граф.
• Поддержать планирование обучения: подсвечивать пробелы и предлагать следующий шаг.
• Служить “лабораторией” для Next.js App Router/RSC, TypeScript, React Compiler, визуализаций и производительности.

Основные сценарии

• Onboarding: ввод профиля (например, “frontend middle React”) → генерация Global Skill Graph.
• Переключение режимов отображения: Global Graph / My Graph (фильтр одного набора данных).
• Навигация по ноде: зависимости вверх, продолжения вниз, фильтры по области/технологии/уровню.
• Ручное редактирование: добавить/удалить ноду, менять уровень, управлять связями.
• Аналитика: общий score и по областям, поиск слабых мест.
• План обучения и roadmap: порядок шагов, приоритеты, прогресс.
• Ресурсы к навыкам: AI-генерация и ручное добавление.

UI-вайрфреймы: docs/ui-templates/1.png, docs/ui-templates/2.png.

---

2. Architecture (C4)

Источник: docs/architecture-overview.md, docs/v1.txt, docs/Вот тебе чистая функциональная.txt.

Context

• Пользователь работает в браузере с персональным графом навыков.
• (Планируется) внешний LLM-провайдер для генерации/анализа (graph, roadmap, summary).
• (Планируется) хранилище состояния графа (in-memory/file/DB — сменяемые адаптеры).

C4Context
title Dev Knowledge Radar — C4 Context

Person(user, "User", "Описывает профиль, исследует граф, отмечает прогресс")
System(app, "Point (Dev Knowledge Radar)", "Граф навыков + метрики + learning plan/roadmap")
System_Ext(llm, "LLM Provider", "Генерация/анализ: graph, roadmap, summary")
System_Ext(storage, "Storage", "Файл/БД (планируемо), хранит состояние графа и артефакты")

Rel(user, app, "Uses", "HTTPS")
Rel(app, llm, "Calls via ai-facade", "API")
Rel(app, storage, "Reads/Writes via persistence", "Adapter")

Loading

Container

Текущий контейнер

• Next.js full-stack приложение (App Router) с рендерингом “server-first” и точечной интерактивностью на клиенте.

Целевая композиция внутри контейнера (модульно)

• knowledge-graph — доменная модель графа и операции над ним.
• learning-plans — построение планов/roadmap на основе графа и зависимостей.
• ai-facade — единая точка интеграции с LLM (generation/analysis) + деградация/фоллбэки.
• persistence — интерфейсы хранения и реализации (заменяемые).
• visualization — визуализация графа (Canvas/WebGL), оптимизации (workers/WASM) — по мере необходимости.

C4Container
title Dev Knowledge Radar — C4 Container (target module layout)

Person(user, "User")

System_Boundary(point, "Point (Next.js full-stack app)") {
  Container(next, "Next.js App", "Next.js (App Router, RSC)", "UI, Server Actions, orchestration")
  Container(kg, "knowledge-graph", "TS domain module", "Graph model, navigation, invariants")
  Container(lp, "learning-plans", "TS domain module", "Learning plan / roadmap building")
  Container(ai, "ai-facade", "Server-side module", "LLM integration, prompts, fallback strategy")
  Container(persist, "persistence", "Port + adapters", "In-memory / file / DB storage")
  Container(viz, "visualization", "Client components", "Canvas/WebGL rendering, interactions")
}

System_Ext(llm, "LLM Provider", "External")

Rel(user, next, "Uses", "HTTPS")
Rel(next, viz, "Renders / controls", "")
Rel(next, kg, "Reads/Writes graph", "")
Rel(next, lp, "Builds plan/roadmap", "")
Rel(next, ai, "Requests generation/analysis", "")
Rel(ai, llm, "Calls", "API")
Rel(next, persist, "Persists state", "")
Rel(kg, persist, "Loads/saves graph", "")
Rel(lp, kg, "Depends on", "")

Loading

Component

UI (план)

• Onboarding: ввод профиля + параметры генерации → Generate.
• Dashboard: центральная панель графа + левая панель деталей навыка + правая панель метрик/плана/ресурсов.
• Roadmap/Learning Plan: шаги обучения, подзадачи, прогресс.
• Edit mode: создание/удаление нод, редактирование связей, сохранение.

Домен/данные (план)

• Контракты: SkillNode, SkillEdge, SkillGraph (+ runtime индексы вроде nodeById, outgoingByNodeId, incomingByNodeId).
• Валидация/нормализация AI-выхода (например, zod), дедупликация и базовые инварианты.
• Метрики и аналитика по User Graph.

C4Component
title Dev Knowledge Radar — C4 Component (UI + server orchestration)

Container_Boundary(next, "Next.js App") {
  Component(onboarding, "Onboarding Page", "RSC + client bits", "Профиль → генерация графа")
  Component(dashboard, "Dashboard", "RSC + client bits", "Граф + детали навыка + аналитика")
  Component(roadmap, "Roadmap/Learning Plan View", "RSC + client bits", "Шаги обучения и прогресс")
  Component(editMode, "Graph Edit Mode", "Client component", "Редактирование нод/связей")

  Component(actions, "Server Actions", "Next.js", "CRUD, validate/normalize, persist")
  Component(domain, "Domain Services", "TS modules", "knowledge-graph + learning-plans")
  Component(aiFacade, "AI Facade", "Server module", "LLM calls + result shaping")
  Component(persist, "Persistence Adapter", "Port + adapter", "Storage implementation")
}

System_Ext(llm, "LLM Provider", "External")

Rel(onboarding, actions, "Generate graph", "")
Rel(dashboard, actions, "CRUD / queries", "")
Rel(roadmap, actions, "Build plan", "")
Rel(editMode, actions, "Edit graph", "")
Rel(actions, domain, "Calls", "")
Rel(actions, persist, "Reads/Writes", "")
Rel(actions, aiFacade, "Calls", "")
Rel(aiFacade, llm, "Calls", "API")

Loading

Code (optional)

Пока реализован только каркас Next.js (src/app/*), доменные модули — в дизайне.

Data Flow (MVP)

flowchart LR
  U[User input: "frontend middle React"] -->|Generate| A[AI generation]
  A -->|skills + edges| V[Validation + normalize]
  V --> G[Persist Global Graph]

  G --> D[Dashboard: render graph]
  D -->|⭐ select nodes| UG[User Graph (subset)]

  UG --> M[Metrics / weak spots]
  UG --> P[Learning Plan / Roadmap]
  G --> P

  D -->|Edit node/edge/level| E[Mutations]
  E --> V
  E --> G

  D -->|Add resources/notes| R[Resources / Notes]
  R --> G

Loading

---

3. Technology Stack

Текущее (по package.json):

• Next.js — full-stack веб-приложение, App Router, RSC/Server Actions (по мере внедрения).
• React / react-dom — UI и композиция компонентов.
• TypeScript — типизация доменных контрактов и UI.
• sass — стили (CSS Modules/SCSS).
• eslint + eslint-config-next — статический анализ.
• babel-plugin-react-compiler + reactCompiler: true — включение React Compiler в Next.

Планируемое (из docs/architecture-overview.md):

• Canvas/WebGL визуализация графа, виртуализация больших списков.
• Web Workers и/или WASM для тяжёлых расчётов (layout/агрегации).
• Адаптеры к LLM-провайдерам (через ai-facade).

---

4. Responsibility Zones

UI

• Экраны/панели (Onboarding, Dashboard, Roadmap, Edit mode).
• Визуализация графа и интерактивность (клиентские компоненты по необходимости).

Business Logic (Domain)

• Модель графа навыков (ноды/связи/уровни), навигация по зависимостям.
• Метрики и аналитика по User Graph.
• Построение Learning Plan / Roadmap.
• Валидация и нормализация данных (включая AI-результаты).

Data Layer

• Хранение: интерфейсы репозиториев и сменяемые реализации (in-memory/file/DB).
• Индексация и представления графа для быстрых запросов (adjacency/edge list/hybrid).

Infrastructure

• Интеграция с LLM (лимиты, ошибки, деградация) через фасад.
• Производительные вычисления (workers/WASM) и профилирование.
• Деплой и окружения (позже).

---

Development

pnpm install
pnpm dev

Стартовая страница: src/app/page.tsx.