Skip to content

PROJECT_STRUCTURE.md

Latest commit

 

History

History
198 lines (170 loc) · 8.13 KB

PROJECT_STRUCTURE.md

File metadata and controls

198 lines (170 loc) · 8.13 KB
Raw

AIKit Project Structure

This document describes the layout of the @gravity-ui/aikit source tree.

File Tree

aikit/
├── .storybook/              # Storybook configuration
├── .claude/                 # Claude Code skills for contributors
├── .cursor/                 # Cursor rules for contributors
├── docs/                    # Documentation (this directory)
│   ├── README.md
│   ├── GETTING_STARTED.md
│   ├── ARCHITECTURE.md
│   ├── PROJECT_STRUCTURE.md
│   ├── COMPONENTS.md
│   ├── THEMING.md
│   ├── HOOKS.md
│   ├── I18N.md
│   ├── EXAMPLES.md
│   ├── TROUBLESHOOTING.md
│   ├── AI_AGENTS.md
│   ├── TESTING.md
│   ├── PLAYWRIGHT.md
│   ├── assets/              # Logos and cover image
│   └── guidelines/          # Internal contributor guidelines (storybook, testing, readme, code-style)
│
├── src/
│   ├── adapters/            # SDK adapters (OpenAI)
│   │   └── openai/
│   │
│   ├── components/
│   │   ├── atoms/           # 16 atoms
│   │   │   ├── ActionButton/   ChatDate/         ContextItem/
│   │   │   ├── Alert/          ContextIndicator/ DiffStat/
│   │   │   ├── Disclaimer/     FileIcon/         InlineCitation/
│   │   │   ├── IntersectionContainer/  Loader/   MarkdownRenderer/
│   │   │   ├── MessageBalloon/ Shimmer/          SubmitButton/
│   │   │   └── ToolIndicator/
│   │   │
│   │   ├── molecules/       # 19 molecules
│   │   │   ├── ActionPopup/    BaseMessage/      ButtonGroup/
│   │   │   ├── FeedbackForm/   FileDropZone/     FileItem/
│   │   │   ├── InputContext/   PromptInputBody/  PromptInputFooter/
│   │   │   ├── PromptInputHeader/  PromptInputPanel/   RatingBlock/
│   │   │   ├── StarRating/     Suggestions/      Tabs/
│   │   │   ├── ToolFooter/     ToolHeader/       ToolStatus/
│   │   │
│   │   ├── organisms/       # 9 organisms
│   │   │   ├── AssistantMessage/   AttachmentPicker/
│   │   │   ├── FileUploadDialog/   Header/        MessageList/
│   │   │   ├── PromptInput/        ThinkingMessage/
│   │   │   ├── ToolMessage/        UserMessage/
│   │   │
│   │   ├── templates/       # 3 templates
│   │   │   ├── ChatContent/        EmptyContainer/   History/
│   │   │
│   │   └── pages/           # 2 pages
│   │       ├── AIStudioChat/       ChatContainer/
│   │
│   ├── hooks/               # 7 public hooks (see docs/HOOKS.md)
│   │   ├── useDateFormatter/
│   │   ├── useToolMessage.tsx
│   │   ├── useSmartScroll.tsx
│   │   ├── useScrollPreservation.ts
│   │   ├── useAutoCollapseOnSuccess.ts
│   │   ├── useAutoCollapseOnCancelled.ts
│   │   └── useFileUploadStore.ts
│   │
│   ├── types/               # TypeScript type definitions
│   │   ├── messages.ts      # TUserMessage, TAssistantMessage, TChatMessage, content types
│   │   ├── chat.ts          # ChatType, ChatStatus, list items
│   │   ├── tool.ts          # ToolMessageProps, statuses
│   │   └── common.ts        # ActionConfig, SuggestionsItem, shared types
│   │
│   ├── utils/               # Public utility modules
│   │   ├── chatUtils.ts
│   │   ├── messageUtils.ts
│   │   ├── validation.ts
│   │   ├── messageTypeRegistry.ts   # MessageRendererRegistry + helpers
│   │   ├── clipboardUtils.ts
│   │   ├── actionUtils.ts
│   │   └── cn.ts            # bem-react classname wrapper
│   │
│   ├── themes/              # Compiled CSS themes
│   │   ├── common.css       # Base CSS variables (always import)
│   │   ├── light.css        # [data-theme='light'] overrides
│   │   ├── dark.css         # [data-theme='dark'] overrides
│   │   └── variables.css    # Deprecated — use common.css
│   │
│   ├── server/              # Server-only code (Node.js)
│   │   └── openai/          # OpenAIService — Responses API wrapper, streaming, summarization
│   │
│   └── index.ts             # Main barrel export
│
├── playwright/              # Docker-backed Playwright runner
├── test-utils/              # Shared test helpers
├── build-utils/             # Build scripts (gulp tasks)
├── build/                   # Compiled output (esm/, cjs/, types)
├── llms.txt                 # LLM agent index (Mantine-style)
├── llms-full.txt            # Concatenated docs for LLM context
├── package.json
├── tsconfig.json
├── playwright-ct.config.ts
├── gulpfile.js
├── README.md / README-ru.md / CLAUDE.md / CONTRIBUTING.md
└── .gitignore / .eslintrc / .prettierrc / …

Source Code: src/

src/components/

Components organized by Atomic Design level. Each component lives in its own directory and follows the structure:

ComponentName/
├── ComponentName.tsx        # Implementation
├── ComponentName.scss       # Styles (optional)
├── types.ts                 # Component types (optional)
├── README.md                # Public API documentation
├── i18n/                    # Localization (optional)
│   ├── index.ts
│   ├── en.json
│   └── ru.json
├── __stories__/
│   ├── ComponentName.stories.tsx
│   └── Docs.mdx
├── __tests__/
│   ├── ComponentName.visual.spec.tsx
│   ├── helpersPlaywright.tsx
│   └── __snapshots__/
└── index.ts                 # Barrel export

Full component catalog: COMPONENTS.md.

src/hooks/

Public hooks exported through both the root entry (from '@gravity-ui/aikit') and the subpath from '@gravity-ui/aikit/hooks'. Internal helpers like useMarkdownTransform and useRemend live in src/hooks/ but are not re-exported.

Full hooks reference: HOOKS.md.

src/types/

Type definitions split by concern: messages, chats, tool messages, common (action configs, suggestions). All re-exported from the root via src/types/index.ts and accessible as import type {…} from '@gravity-ui/aikit' or from '@gravity-ui/aikit/types'.

src/utils/

Each utility is exposed both via the root barrel and a dedicated subpath: @gravity-ui/aikit/utils/chatUtils, /messageUtils, /validation, /messageTypeRegistry, /clipboardUtils.

src/themes/

CSS theming files. Import via subpaths:

import '@gravity-ui/aikit/themes/common';
import '@gravity-ui/aikit/themes/light'; // or '/dark'

variables.css is deprecated — keep common.css only.

src/server/openai/

Server-side only code, builds into a separate CommonJS/ESM target via tsconfig.{esm,cjs}.json and is exposed as the subpath @gravity-ui/aikit/server/openai. Pulls in openai and semver from optionalDependencies.

Naming Conventions

  • Component folders & files: PascalCase (e.g. PromptInput/PromptInput.tsx)
  • Hooks: useThing.ts (or .tsx when JSX is present)
  • Types files: camelCase.ts
  • Test files: <Name>.visual.spec.tsx (Playwright), <Name>.unit.test.ts (Jest)
  • Story files: <Name>.stories.tsx

Export Hierarchy

ComponentName/index.ts
  → src/components/<level>/index.ts
    → src/components/index.ts (implicit via src/index.ts re-exports each level)
      → src/index.ts

Each component additionally has a dedicated subpath in package.json#exports (@gravity-ui/aikit/ComponentName) for tree-shaken imports.

Useful Links