Structure

Top-Level Folder Structure

Folder	Description
`apps/`	Deployable targets consisting of views.
`assets/`	Icon, illustration, image, and font files consumed throughout the repository.
`components/`	Reusable render-able functions mapping 1-to-1 to a unified design system.
`constants`	Constant and cross-package information, such as menu item metadata.
`containers/`	One or more components that manage a portion of business logic.
`contexts/`	Contextual functions to provide information to component descendants.
`docs/`	Docs hoisted to the top-level for simpler search by technical writers.
`e2e`	E2E tests and playwright configuration files.
`hooks/`	Custom hooks to encapsulate stateful logic reused across components.
`integrations/`	Critical user flow testing, likely against mocked data.
`scripts/`	Functions for repository management, automated onboarding, etc.
`themes/`	Source of truth for design system definitions and component overrides.
`translations`	Translation files and react-i18next configuration.
`types`	Contains type declarations defined as a path in tsconfig.json files.
`utils/`	Common functions for manipulating, normalizing, and calculating data.
`views/`	A rendered route comprising containers and components.

It is strongly recommended to navigate to each README.md link above to learn more about each folder's concern.

Package Folder Structure

File Path	Required	Purpose
`src/<NAME>/`	true
└ `index.ts`	true	Exports all variables from `<NAME>.tsx` files
└ `<NAME>.tsx?`	true	Core functionality
└ `<NAME>.spec.tsx`	true	Test file
`src/index.ts`	true	Exports all variables from `<NAME>` folders.
`package.json`	true	Package manifest
`project.json`	true	Nx target project configuration
`README.md`	true	Details what the package is about
`tsconfig.json`	true	Necessary for accessing other packages in the repository.
`tsconfig.<x>.json`	false	Extended configurations for testing, storybook, and the like.
`vite.config.ts`	true	Vite is our go-to builder and tester.

Each package can have multiple <NAME> targets. For example, a src folder may have Form/ and Table/. Moreover, as long as the targets are related, each <NAME>folder may have sub-component “specifiers”, such as Form.tsx, FormField.tsx and FormActions.tsx.

Each package must not relatively import from outside itself—this is an enforced rule by Nx as well. If it needs access to another package, the package must use the scoped package import, such as @halcyon-ai/utils instead of ../../utils.

Note: There are manual onboarding steps detailed here.