hono: Architecture

Architecture health: 52/100 (F)

Overview

hono is a JavaScript/TypeScript project, built with React and Express. It is a library of 1 package. The main structural risks to watch: 4 oversized "god" files and 3 circular import chains. The file with the widest blast radius is src/types.ts: types used by 52 modules; oversized and doing too much.

_This entire analysis runs on your machine with no AI required. Connect a model provider to also narrate the reasoning and recover decisions._

Where to start

1. src/index.ts Start here: how the system boots and wires its subsystems together.
2. src/context.ts Core module: 70 other modules depend on it, so it shapes much of the system.
3. src/hono.ts Core module: 70 other modules depend on it, so it shapes much of the system.
4. src/types.ts Core module: 61 other modules depend on it, so it shapes much of the system.
5. src/http-exception.ts Core module: 20 other modules depend on it, so it shapes much of the system.
6. src/utils/basic-auth.ts Key flow: Authentication, a high-risk path that enters at invoke basic-auth.ts (src/utils/basic-auth.ts).
7. src/middleware/secure-headers/permissions-policy.ts Key flow: Mission execution, a high-risk path that enters at invoke permissions-policy.ts (src/middleware/secure-headers/permissions-policy.ts).
8. src/helper/streaming/index.ts Key flow: AI provider call, a high-risk path that enters at invoke index.ts (src/helper/streaming/index.ts).
9. benchmarks/http-server/benchmark.ts Key flow: File changes / writes, a high-risk path that enters at invoke benchmark.ts (benchmarks/http-server/benchmark.ts).
10. src/jsx/base.ts Change with care: 7 files depend on it at runtime; types used by 10 modules; part of an import cycle.

System map

flowchart TD
  subgraph sys_boundary["hono"]
    hono["hono"]
  end
  class hono library
  classDef frontend fill:#2563eb,stroke:#93c5fd,color:#fff,stroke-width:2px;
  classDef service fill:#059669,stroke:#6ee7b7,color:#fff,stroke-width:2px;
  classDef store fill:#d97706,stroke:#fcd34d,color:#fff,stroke-width:2px;
  classDef queue fill:#9333ea,stroke:#d8b4fe,color:#fff,stroke-width:2px;
  classDef job fill:#4f46e5,stroke:#a5b4fc,color:#fff,stroke-width:2px;
  classDef external fill:#475569,stroke:#cbd5e1,color:#fff,stroke-width:2px;
  classDef aiprovider fill:#e11d48,stroke:#fda4af,color:#fff,stroke-width:2px;
  classDef library fill:#0891b2,stroke:#67e8f9,color:#fff,stroke-width:2px;
  classDef cli fill:#0d9488,stroke:#5eead4,color:#fff,stroke-width:2px;
  classDef user fill:#64748b,stroke:#e2e8f0,color:#fff,stroke-width:2px;
  classDef muted fill:#334155,stroke:#64748b,color:#cbd5e1,stroke-width:1px;

Critical flows

Application startup high risk

Entry: process start (src/index.ts)

Boot wires every subsystem together; a fault here stops the whole process from starting. It also passes through a fragile zone (hono.ts), widening the blast radius.

sequenceDiagram
  actor C0 as Process
  participant F0 as src/index.ts
  participant F1 as hono.ts
  participant F2 as types.ts
  participant F3 as context.ts
  participant F4 as request.ts
  participant F5 as client/index.ts
  C0->>F0: process start
  F0->>F1: calls
  F0->>F2: calls
  F0->>F3: calls
  F0->>F4: calls
  F0->>F5: calls

Authentication high risk

Entry: invoke basic-auth.ts (src/utils/basic-auth.ts)

Authentication guards every protected resource; a regression here can expose data or grant unauthorized access.

sequenceDiagram
  actor C0 as Caller
  participant F0 as basic-auth.ts
  participant F1 as cookie/index.ts
  participant F2 as basic-auth/index.ts
  participant F3 as bearer-auth/index.ts
  participant F4 as jwk.ts
  participant F5 as jwt/index.ts
  C0->>F0: invoke basic-auth.ts

Mission execution high risk

Entry: invoke permissions-policy.ts (src/middleware/secure-headers/permissions-policy.ts)

Mission execution drives autonomous code changes; errors here corrupt runs or the target repository.

sequenceDiagram
  actor C0 as Caller
  participant F0 as permissions-policy.ts
  C0->>F0: invoke permissions-policy.ts

AI provider call high risk

Entry: invoke index.ts (src/helper/streaming/index.ts)

sends a prompt and receives a completion (AI provider)

Provider calls cost money and shape model output; mistakes leak prompts, burn budget, or route to the wrong model.

sequenceDiagram
  actor C0 as Caller
  participant F0 as index.ts
  participant F1 as text.ts
  participant AI as AI provider
  C0->>F0: invoke index.ts
  F0->>AI: sends a prompt and receives a completion
  F0->>F1: calls
  F1->>AI: sends a prompt and receives a completion

File changes / writes high risk

Entry: invoke benchmark.ts (benchmarks/http-server/benchmark.ts)

writes files to the working tree (disk); calls an external service (external API)

Direct writes to the working tree are hard to reverse; an unguarded write can clobber user code.

sequenceDiagram
  actor C0 as Caller
  participant F0 as benchmark.ts
  participant F1 as check-bundle-size.ts
  participant F2 as generate-app.ts
  participant F3 as bun/ssg.ts
  participant F4 as deno/ssg.ts
  participant F5 as ssg/ssg.ts
  participant Disk as disk
  participant External as external API
  C0->>F0: invoke benchmark.ts
  F0->>Disk: writes files to the working tree
  F0->>External: calls an external service
  F1->>Disk: writes files to the working tree
  F2->>Disk: writes files to the working tree
  F3->>Disk: writes files to the working tree
  F4->>Disk: writes files to the working tree
  F5->>Disk: writes files to the working tree
  F5->>External: calls an external service

Background jobs medium risk

Entry: GET / (runtime-tests/workerd/index.ts)

calls an external service (external API); returns a response to the caller (client)

Background jobs run unattended; failures are silent and can pile up unnoticed.

sequenceDiagram
  actor C0 as Scheduler
  participant F0 as workerd/index.ts
  participant F1 as cloudflare-workers/index.ts
  participant F2 as serve-static-module.ts
  participant F3 as websocket.ts
  participant F4 as conninfo.ts
  participant F5 as serve-static.ts
  C0->>F0: GET /
  F0->>F1: calls
  F1->>F2: calls
  F1->>F3: calls
  F1->>F4: calls
  F2->>F5: calls

Fragile zones

• src/types.ts (score 56): types used by 52 modules; oversized and doing too much
• src/context.ts (score 50.5): 7 files depend on it at runtime; types used by 32 modules; oversized and doing too much
• src/jsx/base.ts (score 30.8): 7 files depend on it at runtime; types used by 10 modules; part of an import cycle
• src/jsx/context.ts (score 27): 10 files depend on it at runtime; part of an import cycle
• src/jsx/constants.ts (score 26): 13 files depend on it at runtime
• src/http-exception.ts (score 24): 12 files depend on it at runtime
• src/router.ts (score 24): 10 files depend on it at runtime
• src/jsx/dom/render.ts (score 21.5): 5 files depend on it at runtime; part of an import cycle; oversized and doing too much
• src/hono.ts (score 21): 3 files depend on it at runtime; types used by 14 modules
• src/utils/html.ts (score 21): 8 files depend on it at runtime
• src/jsx/hooks/index.ts (score 18.5): 6 files depend on it at runtime; part of an import cycle
• src/helper/html/index.ts (score 18.3): 9 files depend on it at runtime

Architecture rules