Code Organization

Status: [ ] Not Started | [ ] In Progress | [ ] Complete | [ ] Approved

This document defines the codebase organization, naming conventions, and module boundaries. Complete this document during the Global Setup phase before creating any feature specifications.

Directory Organization

Root Structure

[TODO: Define root directory structure]

Example:
project-root/
├── .flowstate/           # FlowState configuration and docs
├── packages/             # Monorepo packages
├── apps/                 # Application entry points
├── libs/                 # Shared libraries
├── tools/                # Build and dev tools
├── docs/                 # Documentation
└── tests/                # Test suites

Package Structure

[TODO: Define package structure]

Example:
packages/{package-name}/
├── src/
│   ├── index.ts         # Public exports
│   ├── types.ts         # Type definitions
│   └── {feature}/       # Feature modules
├── tests/               # Package tests
├── package.json
├── tsconfig.json
└── README.md

Naming Conventions

Files and Directories

Code Elements

Database and API

Module Boundaries

Package Dependencies

[TODO: Define dependency rules]

Example:
apps/* → packages/*     (allowed)
packages/* → libs/*     (allowed)
libs/* → packages/*     (NOT allowed - circular)

Layer Architecture

[TODO: Define layer structure]

Example:
UI Layer (components)
    ↓
Application Layer (hooks, services)
    ↓
Domain Layer (models, business logic)
    ↓
Infrastructure Layer (API, database)

Import Patterns

Import Order

// [TODO: Define import order]

// Example:
// 1. External dependencies
import React from 'react';
import { useQuery } from '@tanstack/react-query';

// 2. Internal packages
import { Button } from '@project/ui';
import { useAuth } from '@project/auth';

// 3. Relative imports
import { UserCard } from './UserCard';
import { formatDate } from '../utils';

// 4. Type imports
import type { User } from '@project/types';

Path Aliases

Component Organization

Component Structure

// [TODO: Define component structure]

// Example:
// 1. Imports
// 2. Types/Interfaces
// 3. Constants
// 4. Helper functions
// 5. Component definition
// 6. Exports

Component Co-location

[TODO: Define co-location rules]

Example:
ComponentName/
├── index.ts              # Public export
├── ComponentName.tsx     # Main component
├── ComponentName.test.tsx # Tests
├── ComponentName.styles.ts # Styles (if applicable)
└── types.ts              # Component-specific types

Test Organization

Test File Placement

Test Structure

// [TODO: Define test structure]

Configuration Files

Standard Config Files

Environment Configuration

Documentation Structure

Documentation Types

Approval

Last Updated: [Date] Document Owner: [Name]