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

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

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

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

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

Hexagonal port/adapter

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

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

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

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

Python namespace package

# myapp/auth/__init__.py
from .session import sign_in, sign_out
from .types import User

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

Acyclic check

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

Module facade

// 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 · Plugin-Architecture
• 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