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

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:

// 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:

# 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:

# 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:

// 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

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:

// 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:

// 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:

// 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

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! **

Getting Started

Reference

MMO & Blueprint

Progress Detail

Codebase Map

Release

Examples

ARCLUX Analysis

Case Study 1: Analyzing a React Component Library

Scenario

Running ARCLUX

Output Analysis

Key Findings & Insights

Action Plan

Case Study 2: Analyzing a Next.js Monorepo

Scenario

Running ARCLUX

Output

Key Findings

Transformation

Case Study 3: Legacy Express Backend Cleanup

Scenario

Running ARCLUX

Findings

Strategy

Lessons from Real Projects

1. Size Doesn’t Matter, Structure Does

2. Circular Dependencies are ALWAYS a Problem

3. Dead Code Accumulates

4. Layer Violations Hide Real Issues

5. Technical Debt is Real

Using These Examples

​ARCLUX Analysis

​Case Study 1: Analyzing a React Component Library

​Scenario

​Running ARCLUX

​Output Analysis

​Key Findings & Insights

​Action Plan

​Case Study 2: Analyzing a Next.js Monorepo

​Scenario

​Running ARCLUX

​Output

​Key Findings

​Transformation

​Case Study 3: Legacy Express Backend Cleanup

​Scenario

​Running ARCLUX

​Findings

​Strategy

​Lessons from Real Projects

​1. Size Doesn’t Matter, Structure Does

​2. Circular Dependencies are ALWAYS a Problem

​3. Dead Code Accumulates

​4. Layer Violations Hide Real Issues

​5. Technical Debt is Real

​Using These Examples

ARCLUX Analysis

Case Study 1: Analyzing a React Component Library

Scenario

Running ARCLUX

Output Analysis

Key Findings & Insights

Action Plan

Case Study 2: Analyzing a Next.js Monorepo

Scenario

Running ARCLUX

Output

Key Findings

Transformation

Case Study 3: Legacy Express Backend Cleanup

Scenario

Running ARCLUX

Findings

Strategy

Lessons from Real Projects

1. Size Doesn’t Matter, Structure Does

2. Circular Dependencies are ALWAYS a Problem

3. Dead Code Accumulates

4. Layer Violations Hide Real Issues

5. Technical Debt is Real

Using These Examples