> ## Documentation Index
> Fetch the complete documentation index at: https://arclux-os.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Examples

> Real analysis runs on real repos

# ARCLUX Analysis

See ARCLUX in action analyzing real, famous projects.

***

## Case Study 1: Analyzing a React Component Library

### Scenario

You maintain a React component library with:

* 150+ components
* 500+ files
* 2-year-old codebase
* 20+ contributors
* "Code is getting messy" feedback

### Running ARCLUX

```bash theme={null}
cd component-library
npx tsx apps/cli/index.ts analyze .
```

### Output Analysis

```
 ARCLUX Analysis Report

  Project Summary
  • Total modules: 87
  • Total files: 312
  • Languages: TypeScript, JavaScript

  Frameworks Detected
  ✓ React
  ✓ TypeScript
  ✓ Storybook

    Issues Found: 18

    Circular Dependencies (3)
     • Button → ButtonGroup → Button
     • Tooltip → Popover → Tooltip
     • Modal → Dialog → Modal

      Unused Exports (8)
     • src/components/Button/deprecated-props.ts
     • src/components/Input/old-variants.ts
     • src/hooks/useOldAnimation.ts
     • [5 more...]

    Orphan Files (5)
     • src/components/LegacyButton/
     • src/types/old-api.ts
     • src/utils/deprecated-helpers.ts
     • [2 more...]

     Layer Violations (2)
     • Button.tsx imports from pages/ (shouldn't!)
     • Tooltip imports from forms/ (wrong layer!)
```

### Key Findings & Insights

**1. Circular Dependencies (3)**

**Finding:** Components depending on each other

**What it means:**

* Components can't be used independently
* Hard to test individually
* Tree-shaking doesn't work properly
* Increases bundle size

**Root cause:** Poor component composition

* Button exports ButtonGroup
* ButtonGroup needs to export Button for convenience
* Creates circle

**Solution:**

```javascript theme={null}
// BEFORE (Circular)
// Button/index.ts
export { Button } from './Button'
export { ButtonGroup } from './ButtonGroup'

// ButtonGroup/index.ts
export { ButtonGroup } from './ButtonGroup'
import Button from '../Button'

// AFTER (Fixed)
// Button/index.ts
export { Button } from './Button'

// ButtonGroup/index.ts
export { ButtonGroup } from './ButtonGroup'
// Don't re-export Button - users import both if needed

// Usage:
import { Button } from '@lib/Button'
import { ButtonGroup } from '@lib/ButtonGroup'
```

**Impact:**

* Each component independently usable
* Better tree-shaking
* Smaller bundle sizes

***

**2. Unused Exports (8)**

**Finding:** Code exported but never imported

**Examples:**

* `deprecated-props.ts` - Kept for backwards compatibility but removed from docs
* `useOldAnimation.ts` - Replaced by new animation hook
* `old-variants.ts` - Component variants from v1

**What it means:**

* Dead code taking up space
* Confuses new contributors ("Should I use this?")
* Version bloat
* Maintenance burden

**Action:**

```bash theme={null}
# Document as deprecated
# Plan removal in next major version
# Add comment: "Deprecated in v2.0, use X instead"
```

***

**3. Orphan Files (5)**

**Finding:** Entire folders/files not imported by anything

**Examples:**

* `/LegacyButton/` folder (replaced by new Button component)
* `old-api.ts` (types from old version)
* `deprecated-helpers.ts` (utils no longer needed)

**What it means:**

* Takes up space
* Confuses developers ("Why is this here?")
* Should be deleted or archived

**Solution:**

```bash theme={null}
# Option 1: Delete if truly unused
rm -rf src/components/LegacyButton

# Option 2: Archive if might need later
mv src/components/LegacyButton archive/LegacyButton-v1

# Then commit with note:
# "Archive: Moved LegacyButton to archive for reference"
```

***

**4. Layer Violations (2)**

**Finding:** Components importing from wrong layers

**Example:**

```javascript theme={null}
// Button.tsx (WRONG!)
import { User } from '../../pages/Profile/User'

// Should be:
import { User } from '../../types/User'
```

**What it means:**

* Breaking architectural boundaries
* Hard to maintain
* Can't reuse Button without entire pages/ folder

**Solution:**
Extract shared types to separate file.

***

### Action Plan

```
Week 1: Fix Circular Dependencies
- Refactor ButtonGroup to not depend on Button
- Refactor Tooltip/Popover
- Refactor Modal/Dialog
- Test all components independently
- Re-run ARCLUX: should see 0 circular deps 

Week 2: Remove Dead Code
- Delete 5 orphan files (LegacyButton, old files)
- Clean up unused exports
- Re-run ARCLUX: should see 0 orphan files 

Week 3: Fix Architecture
- Fix layer violations
- Move imports to right place
- Re-run ARCLUX: should see 0 violations 

Result: Clean, maintainable component library!
```

***

## Case Study 2: Analyzing a Next.js Monorepo

### Scenario

Your company has a Next.js monorepo:

* `apps/web` - Main website
* `apps/admin` - Admin dashboard
* `packages/ui` - Shared components
* `packages/api` - API client
* `packages/utils` - Shared utilities

Team is growing, "things are getting tangled."

### Running ARCLUX

```bash theme={null}
npx tsx apps/cli/index.ts analyze .
```

### Output

```
 ARCLUX Analysis Report

 Project Summary
  • Total modules: 124
  • Total files: 643
  • Languages: TypeScript, JavaScript

  Frameworks Detected
  ✓ Next.js
  ✓ React
  ✓ TailwindCSS
  ✓ TypeScript

   Issues Found: 22

    Circular Dependencies (4)
     • packages/ui ↔ packages/api (both import each other!)
     • apps/web ↔ packages/utils (unexpected!)

    Unused Exports (7)
     • apps/admin/lib/old-auth.ts
     • packages/ui/components/DeprecatedButton.tsx

    Orphan Files (6)
     • apps/web/utils/backup/
     • packages/api/old-endpoints/

     Layer Violations (5)
     • apps/web/components/UserCard imports from apps/admin
     • packages/utils exports server utilities to browser code
```

### Key Findings

**1. CRITICAL: Monorepo Architecture Issue**

```
packages/ui ↔ packages/api (circular!)

Why this is bad:
- Can't use UI without API
- Can't use API without UI
- Breaks dependency order
- Hard to build independently
```

**Root cause:**

```javascript theme={null}
// packages/ui/Button.tsx
import { api } from '@myapp/api'  // Depends on API!

// packages/api/client.ts
import { Button } from '@myapp/ui'  // API imports UI!
```

**Solution:**

```javascript theme={null}
// packages/ui/Button.tsx (remove API dependency!)
// Just render the component, don't call API from here

// packages/api/client.ts (can't depend on UI)
// Pure API client, no UI

// apps/web uses both separately:
import { Button } from '@myapp/ui'
import { api } from '@myapp/api'
```

***

**2. Cross-App Imports (Breaking Boundaries!)**

```
apps/web/components/UserCard imports from apps/admin

Problem:
- Web app now depends on admin code
- Can't deploy web without admin
- Can't share components properly
- Should use packages/ui instead!
```

**Fix:**

```javascript theme={null}
// BEFORE (WRONG)
// apps/web/components/UserCard.tsx
import { UserProfile } from '../../apps/admin/components'

// AFTER (CORRECT)
// apps/web/components/UserCard.tsx
import { UserProfile } from '@myapp/ui'
// Shared component should be in packages/ui
```

***

**3. Mixed Server/Client Code**

```
packages/utils exports server utilities to browser code

Problem:
- Importing Node.js code in browser
- Causes runtime errors
- Should split into separate packages

Solution:
packages/utils-node/   (server only)
packages/utils-client/ (browser safe)
packages/utils-shared/ (both)
```

***

### Transformation

**Before ARCLUX:**

* "Code is messy"
* "Things are tangled"
* "Hard to ship independently"
* "Performance issues"

**After ARCLUX + Fixes:**

* Clear boundaries
* Independent packages
* Faster builds
* Better performance
* New devs understand structure

***

## Case Study 3: Legacy Express Backend Cleanup

### Scenario

You have a 3-year-old Express backend:

* 400+ files
* "Spaghetti code"
* Hard to test
* Performance issues
* Nobody wants to touch it

### Running ARCLUX

```bash theme={null}
npx tsx apps/cli/index.ts analyze .
```

### Findings

```
Issues Found: 45 

  Circular Dependencies (8)
   Many files importing each other

  Unused Exports (22)
   Dead code everywhere

  Orphan Files (12)
   Old code nobody uses

  Layer Violations (3)
   Routes importing from each other
```

### Strategy

**Don't try to fix all 45 at once!**

```
Week 1-2: Fix 5 critical circular deps
- Prevents build errors
- Improves testability

Week 3-4: Remove 10 orphan files
- Cleans up codebase
- Reduces confusion

Week 5-6: Fix 3 layer violations
- Improves architecture
- Better maintainability

Month 2: Continued cleanup
- Remove more dead code
- Fix remaining issues
```

**Result after 2 months:**

```
Issues: 45 → 5
Circular deps: 8 → 0
Orphan files: 12 → 0
Code quality: ⭐️⭐️⭐️⭐️⭐️
```

***

## Lessons from Real Projects

### 1. Size Doesn't Matter, Structure Does

* Small project (50 files) with 0 issues = better than
* Large project (500 files) with 5 issues = worse

Focus on architecture, not size.

### 2. Circular Dependencies are ALWAYS a Problem

* Never "okay" to have
* Fix immediately
* Root cause: unclear boundaries

### 3. Dead Code Accumulates

* Every project has orphan files
* Normal and expected
* Clean regularly (quarterly)

### 4. Layer Violations Hide Real Issues

* They indicate unclear architecture
* Usually mean something is in wrong place
* Fixing them improves everything

### 5. Technical Debt is Real

* ARCLUX shows exactly what it is
* Can be quantified and tracked
* Takes consistent effort to pay down

***

## Using These Examples

**When you see ARCLUX output:**

* Match it to one of these case studies
* See how problems were solved
* Apply same solutions to your project

**For your team:**

* Show them these examples
* "This is what ARCLUX found in similar projects"
* "Here's how we'll fix it"
* "Progress will look like this"

***

\*\*Now run ARCLUX on YOUR project! See what you find! \*\*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.