2nd/10_Wiki/Topics/Architecture/Modular-Programming.md

---
id: wiki-2026-0508-modular-programming
title: Modular Programming
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Modularity, Module System, Separation of Concerns]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [modularity, architecture, software-design, decoupling]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: typescript
  framework: any
---

# Modular Programming

## 매 한 줄
> **"매 module = 1 concern, 1 contract, 1 owner"**. Parnas 1972 의 information hiding 매 origin. 2026 modular 의 매 form: ES modules, Rust crates, Python packages, Bazel targets — 매 boundary 의 explicit dependency graph.

## 매 핵심

### 매 원칙
- **High cohesion**: 매 module 의 single responsibility.
- **Low coupling**: 매 inter-module 의 narrow interface.
- **Information hiding**: 매 implementation detail 의 hide. Public surface 의 minimize.
- **Acyclic dependency**: 매 graph 의 DAG. Cycle = refactor signal.

### 매 boundary type
- **Logical**: namespace / package.
- **Physical**: separate compile unit / artifact.
- **Process**: separate deployable (microservice).
- **Trust**: separate security domain.

### 매 응용
1. Library author: 매 stable public API + private internals.
2. App architect: 매 feature module + shared kernel.
3. Platform team: 매 plugin host + extension points.

## 💻 패턴

### ES Module barrel + private
```typescript
// src/auth/index.ts (public surface)
export { signIn, signOut } from "./session";
export type { User } from "./types";

// src/auth/_internal/hash.ts (convention: _ prefix = private)
export function hashPassword(p: string) { /* ... */ }

// consumer
import { signIn } from "@/auth"; // ✅
import { hashPassword } from "@/auth/_internal/hash"; // ❌ lint rule
```

### ESLint boundary rule
```json
{
  "rules": {
    "no-restricted-imports": ["error", {
      "patterns": [{
        "group": ["**/_internal/**"],
        "message": "Internal module — import via public barrel."
      }]
    }]
  }
}
```

### Hexagonal port/adapter
```typescript
// port (module boundary)
export interface UserRepo {
  find(id: string): Promise<User | null>;
  save(u: User): Promise<void>;
}

// adapter (Postgres impl)
export class PgUserRepo implements UserRepo {
  constructor(private db: Pool) {}
  async find(id: string) { /* ... */ }
  async save(u: User) { /* ... */ }
}

// core (depends on port only)
export class UserService {
  constructor(private repo: UserRepo) {}
  async promote(id: string) {
    const u = await this.repo.find(id);
    if (!u) throw new Error("not found");
    u.role = "admin";
    await this.repo.save(u);
  }
}
```

### Dependency injection
```typescript
const repo = new PgUserRepo(pool);
const svc = new UserService(repo);

// test: swap impl
const fake: UserRepo = { find: async () => mockUser, save: async () => {} };
new UserService(fake);
```

### Rust crate boundary
```toml
# Cargo.toml
[workspace]
members = ["crates/core", "crates/api", "crates/db"]

[workspace.dependencies]
core = { path = "crates/core" }
```

### Python namespace package
```python
# myapp/auth/__init__.py
from .session import sign_in, sign_out
from .types import User

__all__ = ["sign_in", "sign_out", "User"]
```

### Acyclic check
```bash
npx madge --circular --extensions ts src/
# Or: nx graph --focus=auth
```

### Module facade
```typescript
// payments/index.ts — single entry point
export const payments = {
  charge: (amt: number) => /* ... */,
  refund: (id: string) => /* ... */,
  webhook: (req: Request) => /* ... */,
};
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Small app (<10k LOC) | Logical modules (folders) |
| Medium (10k-100k) | Package boundary + barrel exports |
| Large (>100k) | Bazel/Nx targets + enforced graph |
| Multi-team | Process boundary (services) |

**기본값**: 매 logical module + barrel + ESLint boundary rule.

## 🔗 Graph
- 부모: [[Software-Architecture]] · [[Information-Hiding]]
- 변형: [[Microservices]] · [[Hexagonal Architecture]] · [[Clean-Architecture]]
- 응용: [[Monorepo]] · [[Library-Design]]
- Adjacent: [[Domain-Driven-Design]] · [[SOLID]]

## 🤖 LLM 활용
**언제**: 매 module boundary 의 propose, dependency graph 의 visualize, refactor 의 split-suggest.
**언제 X**: 매 domain ownership decision, team org boundary — Conway's law 의 human judgment.

## ❌ 안티패턴
- **God module**: 매 utils.ts 의 1000+ exports. Cohesion = 0.
- **Circular dependency**: A → B → A. Test 의 hard, build 의 slow.
- **Leaky abstraction**: public surface 의 internal type 의 expose.
- **Premature modularization**: 100 LOC 매 5개 module = over-engineering.

## 🧪 검증 / 중복
- Verified (Parnas 1972 "On the Criteria...", Clean Architecture by Martin, Software Engineering at Google).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — modular programming principles + boundary patterns |