# ArchiTools — Repository Structure Reference

This document describes every planned directory and key file in the ArchiTools repository. It serves as the canonical reference for where code belongs, what each directory contains, and what naming conventions to follow.

---

## Complete Directory Tree

```
ArchiTools/
├── docs/                              # Internal technical documentation
│   ├── architecture/                  # Architecture design documents
│   │   └── SYSTEM-ARCHITECTURE.md     # Platform architecture overview
│   ├── guides/                        # Developer and operational guides
│   │   ├── MODULE-DEVELOPMENT.md      # How to build a new module
│   │   ├── STORAGE-LAYER.md           # Storage abstraction usage
│   │   ├── FEATURE-FLAGS.md           # Feature flag system guide
│   │   ├── HTML-INTEGRATION.md        # Legacy HTML tool integration
│   │   ├── DOCKER-DEPLOYMENT.md       # Build, deploy, and operate
│   │   ├── CODING-STANDARDS.md        # Code style and conventions
│   │   └── UI-DESIGN-SYSTEM.md        # Theme, components, layout rules
│   └── modules/                       # Module-specific design docs
│       ├── REGISTRATURA.md            # Registratura module design
│       ├── PROMPT-GENERATOR.md        # Prompt Generator module design
│       └── ...                        # One doc per complex module
│
├── src/                               # All application source code
│   ├── app/                           # Next.js App Router (routing layer)
│   │   ├── layout.tsx                 # Root layout
│   │   ├── page.tsx                   # Dashboard home page
│   │   ├── globals.css                # Tailwind directives + global styles
│   │   ├── not-found.tsx              # Custom 404 page
│   │   └── (modules)/                 # Route group for all modules
│   │       ├── registratura/
│   │       │   ├── page.tsx           # Module list/main view
│   │       │   ├── layout.tsx         # Module-level layout (optional)
│   │       │   └── [id]/
│   │       │       └── page.tsx       # Detail/edit view
│   │       ├── email-signature/
│   │       │   └── page.tsx
│   │       ├── word-xml/
│   │       │   └── page.tsx
│   │       ├── prompt-generator/
│   │       │   └── page.tsx
│   │       ├── digital-signatures/
│   │       │   └── page.tsx
│   │       ├── password-vault/
│   │       │   └── page.tsx
│   │       ├── it-inventory/
│   │       │   └── page.tsx
│   │       ├── address-book/
│   │       │   └── page.tsx
│   │       ├── word-templates/
│   │       │   └── page.tsx
│   │       ├── tag-manager/
│   │       │   └── page.tsx
│   │       ├── mini-utilities/
│   │       │   └── page.tsx
│   │       └── ai-chat/
│   │           └── page.tsx
│   │
│   ├── core/                          # Platform core systems
│   │   ├── module-registry/
│   │   │   ├── registry.ts            # Module catalog and lookup functions
│   │   │   ├── types.ts               # ModuleConfig, ModuleCategory types
│   │   │   └── index.ts               # Public API
│   │   ├── feature-flags/
│   │   │   ├── flag-service.ts        # Flag resolution logic
│   │   │   ├── flag-provider.tsx       # React context provider
│   │   │   ├── use-feature-flag.ts    # Hook for flag checks
│   │   │   ├── feature-gate.tsx       # Conditional render component
│   │   │   ├── types.ts               # FeatureFlag, FlagScope types
│   │   │   └── index.ts               # Public API
│   │   ├── storage/
│   │   │   ├── storage-service.ts     # StorageService interface definition
│   │   │   ├── storage-provider.tsx   # React context provider
│   │   │   ├── use-storage.ts         # Hook for storage access
│   │   │   ├── adapters/
│   │   │   │   ├── local-storage.ts   # localStorage adapter (current)
│   │   │   │   ├── minio.ts           # MinIO adapter (planned)
│   │   │   │   └── database.ts        # Database adapter (planned)
│   │   │   ├── types.ts               # StorageAdapter, StorageOptions types
│   │   │   └── index.ts               # Public API
│   │   ├── tagging/
│   │   │   ├── tag-service.ts         # Tag CRUD and query logic
│   │   │   ├── use-tags.ts            # Hook for tag operations
│   │   │   ├── types.ts               # Tag, TagCategory types
│   │   │   └── index.ts               # Public API
│   │   ├── i18n/
│   │   │   ├── i18n-provider.tsx      # React context provider
│   │   │   ├── use-label.ts           # Hook for label access
│   │   │   ├── label.tsx              # <Label> component
│   │   │   ├── locales/
│   │   │   │   └── ro.ts             # Romanian labels (current)
│   │   │   ├── types.ts               # LabelKey, Locale types
│   │   │   └── index.ts               # Public API
│   │   ├── theme/
│   │   │   ├── theme-provider.tsx     # Theme context with dark/light toggle
│   │   │   ├── use-theme.ts           # Hook for theme access
│   │   │   ├── tokens.ts             # Design token definitions
│   │   │   └── index.ts               # Public API
│   │   └── auth/
│   │       ├── auth-provider.tsx      # Auth context provider (stub)
│   │       ├── use-auth.ts            # Hook for auth state
│   │       ├── types.ts               # User, UserRole, AuthContext types
│   │       └── index.ts               # Public API
│   │
│   ├── modules/                       # Module business logic
│   │   ├── registratura/
│   │   │   ├── components/
│   │   │   │   ├── entry-form.tsx     # Registry entry form
│   │   │   │   ├── entry-table.tsx    # Entry list table
│   │   │   │   └── entry-card.tsx     # Entry summary card
│   │   │   ├── hooks/
│   │   │   │   ├── use-entries.ts     # Entry CRUD state management
│   │   │   │   └── use-entry-filters.ts
│   │   │   ├── services/
│   │   │   │   ├── entry-service.ts   # Entry business logic
│   │   │   │   └── validation.ts      # Entry validation rules
│   │   │   ├── types.ts               # RegistryEntry, EntryStatus, etc.
│   │   │   ├── config.ts             # Module registration config
│   │   │   └── index.ts              # Public barrel export
│   │   ├── email-signature/
│   │   │   ├── components/
│   │   │   ├── hooks/
│   │   │   ├── services/
│   │   │   ├── types.ts
│   │   │   ├── config.ts
│   │   │   └── index.ts
│   │   ├── word-xml/
│   │   │   ├── components/
│   │   │   ├── hooks/
│   │   │   ├── services/
│   │   │   ├── types.ts
│   │   │   ├── config.ts
│   │   │   └── index.ts
│   │   ├── prompt-generator/
│   │   │   ├── components/
│   │   │   ├── hooks/
│   │   │   ├── services/
│   │   │   ├── templates/             # Prompt template data files
│   │   │   ├── types.ts
│   │   │   ├── config.ts
│   │   │   └── index.ts
│   │   ├── digital-signatures/
│   │   │   ├── components/
│   │   │   ├── hooks/
│   │   │   ├── services/
│   │   │   ├── types.ts
│   │   │   ├── config.ts
│   │   │   └── index.ts
│   │   ├── password-vault/
│   │   │   ├── components/
│   │   │   ├── hooks/
│   │   │   ├── services/
│   │   │   ├── types.ts
│   │   │   ├── config.ts
│   │   │   └── index.ts
│   │   ├── it-inventory/
│   │   │   ├── components/
│   │   │   ├── hooks/
│   │   │   ├── services/
│   │   │   ├── types.ts
│   │   │   ├── config.ts
│   │   │   └── index.ts
│   │   ├── address-book/
│   │   │   ├── components/
│   │   │   ├── hooks/
│   │   │   ├── services/
│   │   │   ├── types.ts
│   │   │   ├── config.ts
│   │   │   └── index.ts
│   │   ├── word-templates/
│   │   │   ├── components/
│   │   │   ├── hooks/
│   │   │   ├── services/
│   │   │   ├── types.ts
│   │   │   ├── config.ts
│   │   │   └── index.ts
│   │   ├── tag-manager/
│   │   │   ├── components/
│   │   │   ├── hooks/
│   │   │   ├── services/
│   │   │   ├── types.ts
│   │   │   ├── config.ts
│   │   │   └── index.ts
│   │   ├── mini-utilities/
│   │   │   ├── components/
│   │   │   ├── hooks/
│   │   │   ├── services/
│   │   │   ├── types.ts
│   │   │   ├── config.ts
│   │   │   └── index.ts
│   │   └── ai-chat/
│   │       ├── components/
│   │       ├── hooks/
│   │       ├── services/
│   │       ├── types.ts
│   │       ├── config.ts
│   │       └── index.ts
│   │
│   ├── shared/                        # Shared UI components and utilities
│   │   ├── components/
│   │   │   ├── ui/                    # shadcn/ui primitives
│   │   │   │   ├── button.tsx
│   │   │   │   ├── input.tsx
│   │   │   │   ├── card.tsx
│   │   │   │   ├── dialog.tsx
│   │   │   │   ├── table.tsx
│   │   │   │   ├── badge.tsx
│   │   │   │   ├── select.tsx
│   │   │   │   ├── tabs.tsx
│   │   │   │   ├── toast.tsx
│   │   │   │   ├── dropdown-menu.tsx
│   │   │   │   └── ...                # Added as needed via shadcn CLI
│   │   │   ├── layout/                # Application shell components
│   │   │   │   ├── app-shell.tsx      # Main layout wrapper
│   │   │   │   ├── sidebar.tsx        # Navigation sidebar
│   │   │   │   ├── header.tsx         # Top header bar
│   │   │   │   ├── footer.tsx         # Optional footer
│   │   │   │   └── breadcrumbs.tsx    # Breadcrumb navigation
│   │   │   └── common/                # Reusable domain components
│   │   │       ├── tag-selector.tsx   # Tag picker (uses tagging core)
│   │   │       ├── company-badge.tsx  # Company indicator
│   │   │       ├── data-table.tsx     # Generic sortable/filterable table
│   │   │       ├── search-input.tsx   # Debounced search field
│   │   │       ├── confirm-dialog.tsx # Confirmation modal
│   │   │       ├── empty-state.tsx    # Empty state placeholder
│   │   │       ├── loading-state.tsx  # Loading skeleton
│   │   │       └── copy-button.tsx    # Copy-to-clipboard button
│   │   ├── hooks/                     # Shared React hooks
│   │   │   ├── use-debounce.ts        # Debounce value hook
│   │   │   ├── use-clipboard.ts       # Clipboard access hook
│   │   │   ├── use-media-query.ts     # Responsive breakpoint hook
│   │   │   └── use-local-state.ts     # Local component state with sync
│   │   └── lib/                       # Shared utility functions
│   │       ├── utils.ts               # General utilities (cn(), formatDate, etc.)
│   │       ├── validators.ts          # Common validation functions
│   │       └── constants.ts           # Shared constants
│   │
│   └── config/                        # Global application configuration
│       ├── modules.ts                 # Module registry (imports all module configs)
│       ├── flags.ts                   # Feature flag defaults
│       ├── navigation.ts             # Navigation structure builder
│       ├── companies.ts              # Company definitions (Beletage, Urban Switch, Studii de Teren)
│       └── external-tools.ts         # External tool links (Stirling PDF, IT-Tools, etc.)
│
├── legacy/                            # Original standalone HTML tools
│   ├── emailsignature/
│   │   └── emailsignature-config.html
│   ├── wordXMLgenerator/
│   │   ├── word-xml-generator-basic.html
│   │   ├── word-xml-generator-medium.html
│   │   └── word-xml-generator-advanced.html
│   └── manicprojects/
│       └── current manic time Tags.txt
│
├── public/                            # Static assets served at root
│   ├── favicon.ico
│   ├── logo.svg                       # Platform logo
│   └── assets/
│       ├── company-logos/             # Company logo variants
│       └── icons/                     # Custom icons if needed
│
├── Dockerfile                         # Multi-stage production build
├── docker-compose.yml                 # Service definition for deployment
├── .env.example                       # Environment variable template
├── .env.local                         # Local dev overrides (gitignored)
├── next.config.ts                     # Next.js configuration
├── tailwind.config.ts                 # Tailwind theme and plugin config
├── tsconfig.json                      # TypeScript compiler configuration
├── postcss.config.mjs                 # PostCSS config (Tailwind plugin)
├── package.json                       # Dependencies and scripts
├── package-lock.json                  # Dependency lock file
├── components.json                    # shadcn/ui configuration
├── .gitignore                         # Git ignore rules
├── .eslintrc.json                     # ESLint configuration
├── .prettierrc                        # Prettier formatting rules
├── CONTEXT.md                         # Project context and requirements
└── LICENSE                            # License file (if applicable)
```

---

## Directory Descriptions

### `docs/`

Internal technical documentation. Not shipped in the Docker image. Organized into three subdirectories:

- **`architecture/`** — System-level design documents. Describes the platform as a whole: architecture overview, data flow, deployment model, security boundaries. These documents change infrequently and are reviewed before major structural changes.

- **`guides/`** — Developer and operational guides. Practical, how-to oriented. Covers module development, storage usage, feature flag configuration, Docker deployment, coding standards, and UI design rules. These are the documents developers consult daily.

- **`modules/`** — Module-specific design documents. One file per complex module. Describes the module's data model, UI structure, business rules, integration points, and edge cases. Simple modules may not need a dedicated doc.

### `src/app/`

Next.js App Router directory. Contains **only routing concerns**: page components, layouts, and metadata. No business logic lives here. Page files are thin wrappers that import and compose components from `src/modules/` and `src/shared/`.

- **`layout.tsx`** — Root layout. Wraps the entire application in the provider stack (Theme, i18n, Storage, FeatureFlags, Auth). Renders the AppShell (sidebar + header + content area). This file should rarely change after initial setup.

- **`page.tsx`** — Dashboard home. Renders the widget grid with module entry points, quick actions, and infrastructure service links.

- **`globals.css`** — Tailwind's `@tailwind` directives, CSS custom properties for theming, and minimal global styles. No component-specific CSS.

- **`not-found.tsx`** — Custom 404 page displayed when navigating to disabled modules or invalid routes.

- **`(modules)/`** — Route group. The parentheses mean this directory does not add a URL segment. All module routes live here, keeping them visually grouped without nesting URLs. Each module subdirectory contains at minimum a `page.tsx`. Complex modules may include `layout.tsx` for module-level navigation (tabs, sub-routes) and dynamic route segments (`[id]/`).

### `src/core/`

Platform core systems. These are infrastructure services used by all modules. Core systems do not contain business logic for any specific module. They provide capabilities that modules consume.

- **`module-registry/`** — Maintains the catalog of all registered modules. Provides lookup functions (by ID, route, category), filtering (by enabled state, role, visibility), and the ordered list used by navigation. The registry reads from `src/config/modules.ts`.

- **`feature-flags/`** — Controls runtime activation of modules and features. Includes the flag resolution service (environment variable > config > default), React context provider, `useFeatureFlag()` hook, and `<FeatureGate>` render guard component. Flags are defined in `src/config/flags.ts`.

- **`storage/`** — Persistence abstraction layer. Defines the `StorageService` interface and provides adapter implementations. The `adapters/` subdirectory contains one file per storage backend. The active adapter is selected at startup based on environment configuration. All module data flows through this service.

- **`tagging/`** — Cross-module tagging system. Provides tag CRUD operations, tag association with entities, and tag-based querying. Tags are stored via the storage abstraction. Multiple modules (Registratura, Prompt Generator, Digital Signatures, etc.) use this service to categorize and cross-reference their entities.

- **`i18n/`** — Internationalization system. Currently Romanian-only, structured for future multi-language support. Labels are organized by namespace (one per module + common). The `locales/` subdirectory contains one file per language. Components access labels via `useLabel()` hook or `<Label>` component.

- **`theme/`** — Dark/light theme system. Provides the theme context, toggle hook, and design token definitions. Theme preference is persisted in storage. Tokens define colors, spacing, and typography values consumed by Tailwind and component styles.

- **`auth/`** — Authentication and authorization stub. Defines the `AuthContext` interface (`user`, `role`, `permissions`, `company`). Currently returns a default admin user. When Authentik SSO integration is implemented, this module will resolve real identity from OIDC tokens. The interface remains stable; only the provider implementation changes.

### `src/modules/`

Module business logic. Each subdirectory is a self-contained module with its own components, hooks, services, types, and configuration. Modules are the primary unit of functionality in ArchiTools.

**Standard module structure:**

| File/Directory | Purpose |
|----------------|---------|
| `components/` | React components specific to this module. Not shared with other modules. |
| `hooks/` | React hooks encapsulating module state and logic. Hooks call services and expose state to components. |
| `services/` | Pure business logic functions. Validation, transformation, computation. No React dependencies. |
| `types.ts` | TypeScript interfaces and types for this module's domain. |
| `config.ts` | `ModuleConfig` object exported for the module registry. Contains ID, name, route, icon, category, feature flag key, and other metadata. |
| `index.ts` | Barrel export. Exposes the module's public API: config, key types, and any components/hooks that other parts of the app need (primarily used by route pages). |

**Module-specific additions:**

Some modules extend the standard structure:

- `prompt-generator/templates/` — Data-driven prompt template definitions (JSON/TS files, not UI components).
- Modules with sub-views may have a `views/` directory alongside `components/` for page-level compositions.

### `src/shared/`

Shared UI components, hooks, and utilities used across multiple modules. Nothing module-specific lives here.

- **`components/ui/`** — shadcn/ui primitive components. These are added via the `npx shadcn@latest add` CLI command and may be customized. They provide the atomic building blocks: buttons, inputs, cards, dialogs, tables, badges, selects, etc. Files in this directory are generated and should be modified sparingly.

- **`components/layout/`** — Application shell components. The sidebar, header, footer, breadcrumbs, and the main app-shell wrapper. These components compose the persistent chrome around module content. They read from the module registry and navigation config to build menu items dynamically.

- **`components/common/`** — Reusable domain-aware components shared across modules. Unlike `ui/` (which are generic primitives), these components encode ArchiTools-specific patterns: tag selectors, company badges, data tables with standard filtering, confirmation dialogs, empty/loading states. Any component needed by two or more modules belongs here.

- **`hooks/`** — Shared React hooks for common browser interactions: debouncing, clipboard access, media queries, local component state synchronization. Module-specific hooks belong in the module's `hooks/` directory, not here.

- **`lib/`** — Pure utility functions and constants. Includes the `cn()` class merge utility (standard shadcn/ui pattern), date formatting, common validators, and shared constants (e.g., date formats, pagination defaults).

### `src/config/`

Global application configuration. Static configuration data that drives runtime behavior.

- **`modules.ts`** — Central module registry data. Imports `config.ts` from every module and exports the complete array. This is the single file that determines which modules the platform knows about.

- **`flags.ts`** — Feature flag default values. Maps flag keys to their default `enabled` state and scope. Environment variables can override these at runtime.

- **`navigation.ts`** — Navigation structure builder. Reads from the module registry, applies feature flag filtering, groups by category, and produces the ordered navigation tree consumed by the sidebar.

- **`companies.ts`** — Company definitions for Beletage SRL, Urban Switch SRL, and Studii de Teren SRL. Contains company ID, name, short name, color, logo path, and any per-company configuration. Used by the Registratura, Email Signature Generator, Address Book, and other multi-company modules.

- **`external-tools.ts`** — Links to external infrastructure services (Stirling PDF, IT-Tools, Filebrowser, N8N, Portainer, etc.) displayed on the dashboard and optionally in navigation.

### `legacy/`

Original standalone HTML tools that predate the ArchiTools platform. These files are preserved for reference and serve as the specification for React module reimplementation. They are not served by the Next.js application.

- **`emailsignature/`** — Email signature generator. Single HTML file with inline CSS/JS. Generates HTML email signatures for company employees.

- **`wordXMLgenerator/`** — Word XML content control binding generators. Three complexity tiers (basic, medium, advanced). Generate XML binding files for Microsoft Word templates.

- **`manicprojects/`** — ManicTime project tag definitions. Text file with time tracking tag categories.

When a legacy tool is fully reimplemented as a React module, the legacy file remains in this directory for archival reference. It is never deleted.

### `public/`

Static assets served at the root URL path by Next.js. Contains the favicon, platform logo, company logos, and any custom icon assets. Keep this directory minimal; most assets should be imported via the build pipeline for optimization.

### Root Configuration Files

| File | Purpose |
|------|---------|
| `Dockerfile` | Multi-stage build: deps install, Next.js build, minimal runtime image. Produces a standalone Next.js server on Node.js Alpine. |
| `docker-compose.yml` | Single-service definition for ArchiTools. References `.env` for environment variables. Defines port mapping, restart policy, and optional volume mounts. |
| `.env.example` | Template for environment variables. Committed to the repo. Documents every variable with comments. Developers copy to `.env.local` for local development. |
| `next.config.ts` | Next.js configuration. Enables standalone output mode (required for Docker), configures image domains, and sets any required headers. |
| `tailwind.config.ts` | Tailwind CSS configuration. Extends the default theme with ArchiTools design tokens, custom colors, and font settings. References content paths for tree-shaking. |
| `tsconfig.json` | TypeScript configuration. Sets strict mode, path aliases (`@/` maps to `src/`), and App Router-compatible settings. |
| `postcss.config.mjs` | PostCSS configuration. Loads the Tailwind CSS plugin. |
| `package.json` | Project metadata, dependencies, and scripts (`dev`, `build`, `start`, `lint`, `format`). |
| `components.json` | shadcn/ui configuration. Defines the component install path (`src/shared/components/ui`), style settings, and Tailwind config path. |
| `.gitignore` | Ignores `node_modules/`, `.next/`, `.env.local`, `.env`, build output, OS files. |
| `.eslintrc.json` | ESLint rules. Extends Next.js defaults with TypeScript-specific rules. |
| `.prettierrc` | Prettier formatting configuration. Single quotes, trailing commas, 2-space indent, 100 character line width. |
| `CONTEXT.md` | Project context and requirements document. The original specification that drives all architecture decisions. |

---

## Directory Conventions

### 1. Separation of Routing and Logic

The `src/app/` directory contains **only routing and layout files**. All business logic, domain components, hooks, and services live in `src/modules/` or `src/shared/`. Route page files are thin: they import a module's components, check feature flags, and render.

```typescript
// src/app/(modules)/registratura/page.tsx — correct (thin wrapper)
import { EntryTable } from '@/modules/registratura';
import { FeatureGate } from '@/core/feature-flags';

export default function RegistraturaPage() {
  return (
    <FeatureGate flag="module.registratura">
      <EntryTable />
    </FeatureGate>
  );
}
```

### 2. Module Self-Containment

Each module directory under `src/modules/` must be fully self-contained. If you delete a module's directory and remove its entry from `src/config/modules.ts`, the application must still build and run without errors. This means:

- No other module imports from this module's internals
- No shared component depends on a specific module
- The module's route page is guarded by a feature flag

### 3. Core Systems Are Not Modules

The `src/core/` directory contains platform infrastructure, not business modules. Core systems are always available regardless of feature flags. They do not have route pages. They provide services consumed by modules and the shell.

### 4. Shared Components Require Multi-Module Use

A component moves to `src/shared/components/common/` only when it is needed by two or more modules. Components used by a single module stay in that module's `components/` directory, even if they seem generic. Premature extraction creates coupling.

### 5. Config Files Are Declarative

Files in `src/config/` are pure data and simple builder functions. They do not contain business logic, side effects, or React components. They export configuration objects and arrays consumed by core systems.

---

## File Naming Rules

### General Rules

| Rule | Convention | Example |
|------|-----------|---------|
| File names | `kebab-case` | `entry-form.tsx`, `use-entries.ts` |
| Directory names | `kebab-case` | `module-registry/`, `email-signature/` |
| React components | `PascalCase` export, `kebab-case` filename | `entry-form.tsx` exports `EntryForm` |
| Hooks | `use-` prefix, `camelCase` export | `use-entries.ts` exports `useEntries` |
| Services | `-service` suffix | `entry-service.ts`, `tag-service.ts` |
| Type files | `types.ts` (one per module/core system) | `src/modules/registratura/types.ts` |
| Config files | `config.ts` (module) or descriptive name (global) | `config.ts`, `flags.ts` |
| Barrel exports | `index.ts` | Every module and core system has one |
| Test files | `.test.ts` / `.test.tsx` co-located | `entry-service.test.ts` |

### Specific Patterns

**React component files:**
```
kebab-case.tsx         →  exports PascalCase component
entry-form.tsx         →  export function EntryForm() {}
confirm-dialog.tsx     →  export function ConfirmDialog() {}
```

**Hook files:**
```
use-kebab-case.ts      →  exports camelCase hook
use-entries.ts         →  export function useEntries() {}
use-feature-flag.ts    →  export function useFeatureFlag() {}
```

**Service files:**
```
kebab-case-service.ts  →  exports named functions
entry-service.ts       →  export function getEntries() {}
tag-service.ts         →  export function createTag() {}
```

**Provider files (React context):**
```
kebab-case-provider.tsx →  exports PascalCase provider component
theme-provider.tsx      →  export function ThemeProvider() {}
storage-provider.tsx    →  export function StorageProvider() {}
```

**Type files:**
```
types.ts                →  exports interfaces and type aliases
                           No default exports in type files
                           One types.ts per module or core system
```

**Config files:**
```
config.ts               →  module config (in module directory)
modules.ts              →  global module registry (in src/config/)
flags.ts                →  global feature flags (in src/config/)
```

### Import Aliases

The `tsconfig.json` defines a path alias:

```json
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

All imports use the `@/` alias. Never use relative paths that traverse above the current module.

```typescript
// Correct
import { StorageService } from '@/core/storage';
import { Button } from '@/shared/components/ui/button';
import { useEntries } from '@/modules/registratura/hooks/use-entries';

// Incorrect
import { StorageService } from '../../../core/storage';
import { something } from '@/modules/other-module/internal-thing';
```

### Language in Code

- All file names: **English**
- All variable, function, class, and type names: **English**
- All code comments: **English**
- All UI-facing strings: **Romanian** (accessed via i18n labels, never hardcoded in components)
- All documentation: **English**

---

## Adding a New Module — Checklist

1. Create `src/modules/[module-name]/` with the standard structure (`components/`, `hooks/`, `services/`, `types.ts`, `config.ts`, `index.ts`)
2. Define `ModuleConfig` in `config.ts`
3. Add the module config import to `src/config/modules.ts`
4. Add the feature flag to `src/config/flags.ts`
5. Create the route directory `src/app/(modules)/[module-name]/page.tsx`
6. Wrap the page content in `<FeatureGate>`
7. Add Romanian labels to `src/core/i18n/locales/ro.ts` under the module namespace
8. If complex, create a design doc in `docs/modules/[MODULE-NAME].md`