Skip to content

hashgraph-online/awesome-codex-plugins / plugins/alpoxdev/hypercore/skills/hyper-architecture

hyper-architecture

Verified

[Hyper] Use this skill when the user asks for architecture, project setup, or performance work - building, auditing, restructuring, or reviewing project structure, routes, data or server boundaries, the lint/format/type tooling baseline (oxlint, Prettier, tsconfig, rustfmt, clippy), or build and runtime performance - in a Next.js App Router, TanStack Start, Vite with TanStack Router, Astro, Expo, Lynx (ReactLynx), Hono, Axum, Tauri v2, Electron, or Rust CLI, WASM, or MCP server project. It detects the stack from manifests and config files, routes each touched package of a monorepo separately, and applies the matching bundled stack guide, the shared setup baseline, and that stack's performance rules. Do not use it for stacks outside those eleven or for work that crosses no architecture, setup, or performance boundary, such as copy edits, a plain dependency bump, or one build failure.

FileKindSize
SKILL.ko.mdmarkdown19.9 KB
SKILL.mdskill md18.4 KB
assets/evals/astro-cases.jsonlother17.1 KB
assets/evals/axum-cases.jsonlother13.7 KB
assets/evals/electron-cases.jsonlother14.6 KB
assets/evals/expo-cases.jsonlother18.3 KB
assets/evals/hono-cases.jsonlother22.2 KB
assets/evals/hyper-architecture-cases.jsonlother26.0 KB
assets/evals/lynx-cases.jsonlother17.9 KB
assets/evals/nextjs-cases.jsonlother21.5 KB
assets/evals/rust-cases.jsonlother17.8 KB
assets/evals/tanstack-start-cases.jsonlother21.0 KB
assets/evals/tauri-cases.jsonlother18.6 KB
assets/evals/vite-cases.jsonlother18.6 KB
assets/templates/setup/repo/editorconfigother357 B
assets/templates/setup/repo/gitattributesother714 B
assets/templates/setup/repo/lefthook.ymlconfig843 B
assets/templates/setup/rust/clippy.tomlconfig110 B
assets/templates/setup/rust/rust-toolchain.tomlconfig86 B
assets/templates/setup/rust/rustfmt.tomlconfig200 B
assets/templates/setup/rust/workspace-lints.tomlconfig809 B
assets/templates/setup/typescript/oxlintrc.jsonconfig929 B
assets/templates/setup/typescript/oxlintrc.react.jsonconfig1.1 KB
assets/templates/setup/typescript/prettierignoreother316 B
assets/templates/setup/typescript/prettierrc.jsonconfig263 B
assets/templates/setup/typescript/tsconfig.base.jsonconfig551 B
references/official/astro/astro-2026-11-07.ko.mdmarkdown18.6 KB
references/official/astro/astro-2026-11-07.mdmarkdown17.0 KB
references/official/axum/axum-docs.ko.mdmarkdown5.7 KB
references/official/axum/axum-docs.mdmarkdown4.8 KB
references/official/axum/ecosystem-docs.ko.mdmarkdown3.8 KB
references/official/axum/ecosystem-docs.mdmarkdown3.5 KB
references/official/axum/sqlx-docs.ko.mdmarkdown5.5 KB
references/official/axum/sqlx-docs.mdmarkdown4.7 KB
references/official/axum/tower-docs.ko.mdmarkdown4.2 KB
references/official/axum/tower-docs.mdmarkdown3.7 KB
references/official/axum/utoipa-docs.ko.mdmarkdown4.1 KB
references/official/axum/utoipa-docs.mdmarkdown3.7 KB
references/official/electron/electron-2026-11-08.ko.mdmarkdown15.7 KB
references/official/electron/electron-2026-11-08.mdmarkdown14.1 KB
references/official/expo/expo-react-native-2026-11-04.ko.mdmarkdown23.0 KB
references/official/expo/expo-react-native-2026-11-04.mdmarkdown21.5 KB
references/official/hono/drizzle-docs.ko.mdmarkdown7.0 KB
references/official/hono/drizzle-docs.mdmarkdown6.6 KB
references/official/hono/hono-docs.ko.mdmarkdown15.8 KB
references/official/hono/hono-docs.mdmarkdown14.8 KB
references/official/lynx/lynx-2026-11-07.ko.mdmarkdown14.3 KB
references/official/lynx/lynx-2026-11-07.mdmarkdown14.0 KB
references/official/nextjs/current-docs-2026-11-04.ko.mdmarkdown13.1 KB
references/official/nextjs/current-docs-2026-11-04.mdmarkdown12.0 KB
references/official/nextjs/drizzle-docs.ko.mdmarkdown6.7 KB
references/official/nextjs/drizzle-docs.mdmarkdown6.3 KB
references/official/nextjs/nextjs-docs.ko.mdmarkdown13.6 KB
references/official/nextjs/nextjs-docs.mdmarkdown13.9 KB
references/official/rust/rust-crates-2026-11-07.ko.mdmarkdown22.6 KB
references/official/rust/rust-crates-2026-11-07.mdmarkdown22.0 KB
references/official/tanstack-start/current-docs-2026-11-04.ko.mdmarkdown16.0 KB
references/official/tanstack-start/current-docs-2026-11-04.mdmarkdown14.7 KB
references/official/tanstack-start/tanstack-router-2026-11-04.ko.mdmarkdown10.5 KB
references/official/tanstack-start/tanstack-router-2026-11-04.mdmarkdown9.6 KB
references/official/tanstack-start/tanstack-start-2026-11-04.ko.mdmarkdown25.8 KB
references/official/tanstack-start/tanstack-start-2026-11-04.mdmarkdown23.9 KB
references/official/tauri/tanstack-vite-react-2026-11-04.ko.mdmarkdown14.1 KB
references/official/tauri/tanstack-vite-react-2026-11-04.mdmarkdown13.1 KB
references/official/tauri/tauri-v2-2026-11-04.ko.mdmarkdown18.5 KB
references/official/tauri/tauri-v2-2026-11-04.mdmarkdown17.6 KB
references/official/tooling/tooling-2026-11-07.ko.mdmarkdown21.0 KB
references/official/tooling/tooling-2026-11-07.mdmarkdown20.5 KB
references/official/vite/current-docs-2026-11-04.ko.mdmarkdown11.2 KB
references/official/vite/current-docs-2026-11-04.mdmarkdown10.3 KB
rules/astro/actions-middleware-env.ko.mdmarkdown14.6 KB
rules/astro/actions-middleware-env.mdmarkdown12.9 KB
rules/astro/content.ko.mdmarkdown8.1 KB
rules/astro/content.mdmarkdown7.3 KB
rules/astro/performance.ko.mdmarkdown11.3 KB
rules/astro/performance.mdmarkdown10.0 KB
rules/astro/project-structure.ko.mdmarkdown11.2 KB
rules/astro/project-structure.mdmarkdown9.6 KB
rules/astro/rendering-and-islands.ko.mdmarkdown10.2 KB
rules/astro/rendering-and-islands.mdmarkdown8.7 KB
rules/astro/testing.ko.mdmarkdown10.4 KB
rules/astro/testing.mdmarkdown9.4 KB
rules/axum/conventions.ko.mdmarkdown5.3 KB
rules/axum/conventions.mdmarkdown4.8 KB
rules/axum/database.ko.mdmarkdown11.9 KB
rules/axum/database.mdmarkdown10.2 KB
rules/axum/errors.ko.mdmarkdown6.5 KB
rules/axum/errors.mdmarkdown6.0 KB
rules/axum/handlers.ko.mdmarkdown5.6 KB
rules/axum/handlers.mdmarkdown5.0 KB
rules/axum/middleware.ko.mdmarkdown5.4 KB
rules/axum/middleware.mdmarkdown4.9 KB
rules/axum/openapi.ko.mdmarkdown9.5 KB
rules/axum/openapi.mdmarkdown8.3 KB
rules/axum/performance.ko.mdmarkdown9.6 KB
rules/axum/performance.mdmarkdown8.6 KB
rules/axum/platform.ko.mdmarkdown6.9 KB
rules/axum/platform.mdmarkdown6.3 KB
rules/axum/project-structure.ko.mdmarkdown10.8 KB
rules/axum/project-structure.mdmarkdown9.9 KB
rules/axum/routes.ko.mdmarkdown7.3 KB
rules/axum/routes.mdmarkdown6.3 KB
rules/axum/testing.ko.mdmarkdown5.2 KB
rules/axum/testing.mdmarkdown4.6 KB
rules/axum/validation.ko.mdmarkdown4.8 KB
rules/axum/validation.mdmarkdown4.4 KB
rules/electron/packaging.ko.mdmarkdown7.9 KB
rules/electron/packaging.mdmarkdown7.0 KB
rules/electron/performance.ko.mdmarkdown5.8 KB
rules/electron/performance.mdmarkdown5.0 KB
rules/electron/processes-and-ipc.ko.mdmarkdown10.6 KB
rules/electron/processes-and-ipc.mdmarkdown9.7 KB
rules/electron/project-structure.ko.mdmarkdown8.8 KB
rules/electron/project-structure.mdmarkdown8.1 KB
rules/electron/renderer.ko.mdmarkdown10.8 KB
rules/electron/renderer.mdmarkdown9.8 KB
rules/electron/security.ko.mdmarkdown10.3 KB
rules/electron/security.mdmarkdown9.2 KB
rules/electron/testing.ko.mdmarkdown5.7 KB
rules/electron/testing.mdmarkdown5.0 KB
rules/expo/data-state-and-boundaries.ko.mdmarkdown4.7 KB
rules/expo/data-state-and-boundaries.mdmarkdown4.3 KB
rules/expo/native-platform-and-security.ko.mdmarkdown8.2 KB
rules/expo/native-platform-and-security.mdmarkdown7.5 KB
rules/expo/performance.ko.mdmarkdown11.2 KB
rules/expo/performance.mdmarkdown10.1 KB
rules/expo/project-structure.ko.mdmarkdown13.4 KB
rules/expo/project-structure.mdmarkdown13.2 KB
rules/expo/routing-and-navigation.ko.mdmarkdown8.6 KB
rules/expo/routing-and-navigation.mdmarkdown8.0 KB
rules/expo/testing-and-validation.ko.mdmarkdown5.1 KB
rules/expo/testing-and-validation.mdmarkdown4.8 KB
rules/hono/conventions.ko.mdmarkdown3.7 KB
rules/hono/conventions.mdmarkdown3.5 KB
rules/hono/database.ko.mdmarkdown11.7 KB
rules/hono/database.mdmarkdown10.8 KB
rules/hono/errors.ko.mdmarkdown3.9 KB
rules/hono/errors.mdmarkdown3.7 KB
rules/hono/handlers.ko.mdmarkdown2.5 KB
rules/hono/handlers.mdmarkdown2.2 KB
rules/hono/middleware.ko.mdmarkdown3.3 KB
rules/hono/middleware.mdmarkdown3.0 KB
rules/hono/openapi.ko.mdmarkdown11.7 KB
rules/hono/openapi.mdmarkdown10.9 KB
rules/hono/performance.ko.mdmarkdown8.9 KB
rules/hono/performance.mdmarkdown8.0 KB
rules/hono/platform.ko.mdmarkdown5.0 KB
rules/hono/platform.mdmarkdown4.7 KB
rules/hono/project-structure.ko.mdmarkdown10.4 KB
rules/hono/project-structure.mdmarkdown9.9 KB
rules/hono/routes.ko.mdmarkdown6.9 KB
rules/hono/routes.mdmarkdown6.6 KB
rules/hono/testing-rpc.ko.mdmarkdown5.6 KB
rules/hono/testing-rpc.mdmarkdown5.2 KB
rules/hono/validation.ko.mdmarkdown3.7 KB
rules/hono/validation.mdmarkdown3.5 KB
rules/lynx/native-and-platform.ko.mdmarkdown11.4 KB
rules/lynx/native-and-platform.mdmarkdown10.7 KB
rules/lynx/performance.ko.mdmarkdown11.6 KB
rules/lynx/performance.mdmarkdown10.6 KB
rules/lynx/project-structure.ko.mdmarkdown10.2 KB
rules/lynx/project-structure.mdmarkdown9.6 KB
rules/lynx/testing.ko.mdmarkdown7.0 KB
rules/lynx/testing.mdmarkdown6.4 KB
rules/lynx/threading.ko.mdmarkdown13.0 KB
rules/lynx/threading.mdmarkdown12.0 KB
rules/lynx/ui-and-data.ko.mdmarkdown11.8 KB
rules/lynx/ui-and-data.mdmarkdown10.8 KB
rules/nextjs/data-fetching.ko.mdmarkdown9.9 KB
rules/nextjs/data-fetching.mdmarkdown9.3 KB
rules/nextjs/db.ko.mdmarkdown8.1 KB
rules/nextjs/db.mdmarkdown7.3 KB
rules/nextjs/execution-model.ko.mdmarkdown5.0 KB
rules/nextjs/execution-model.mdmarkdown4.5 KB
rules/nextjs/hooks.ko.mdmarkdown5.8 KB
rules/nextjs/hooks.mdmarkdown5.3 KB
rules/nextjs/performance.ko.mdmarkdown12.5 KB
rules/nextjs/performance.mdmarkdown11.2 KB
rules/nextjs/platform.ko.mdmarkdown7.7 KB
rules/nextjs/platform.mdmarkdown7.0 KB
rules/nextjs/project-structure.ko.mdmarkdown9.4 KB
rules/nextjs/project-structure.mdmarkdown9.0 KB
rules/nextjs/route-handlers.ko.mdmarkdown4.7 KB
rules/nextjs/route-handlers.mdmarkdown4.3 KB
rules/nextjs/routes.ko.mdmarkdown5.0 KB
rules/nextjs/routes.mdmarkdown4.6 KB
rules/nextjs/server-actions.ko.mdmarkdown7.1 KB
rules/nextjs/server-actions.mdmarkdown6.4 KB
rules/nextjs/services.ko.mdmarkdown5.8 KB
rules/nextjs/services.mdmarkdown5.5 KB
rules/nextjs/validation.ko.mdmarkdown2.2 KB
rules/nextjs/validation.mdmarkdown2.3 KB
rules/rust/cli.ko.mdmarkdown13.6 KB
rules/rust/cli.mdmarkdown12.0 KB
rules/rust/crate-layout.ko.mdmarkdown11.4 KB
rules/rust/crate-layout.mdmarkdown10.1 KB
rules/rust/errors-and-logging.ko.mdmarkdown13.0 KB
rules/rust/errors-and-logging.mdmarkdown11.6 KB
rules/rust/mcp-server.ko.mdmarkdown15.2 KB
rules/rust/mcp-server.mdmarkdown13.8 KB

rules/axum/openapi.md

View on GitHub
# OpenAPI and Swagger

> Treat the generated document as a typed contract boundary

---
## Stable Package Baseline

As verified on 2026-11-05, `utoipa` is 6.0.0, `utoipa-axum` is 0.3.0, and `utoipa-swagger-ui` is 10.0.2; the utoipa crates require Rust 1.88. utoipa 6 adds OpenAPI 3.2 support via `Version32`. The rendered documentation is internally inconsistent about the default emitted version, because the feature list says 3.1 while the `openapi` module describes 3.2, so declare the target version explicitly in the `OpenApi` builder instead of assuming one.

- Prefer `utoipa` derives on DTOs plus `#[utoipa::path]` on handlers, and compose with `utoipa-axum` `OpenApiRouter` when the repository already uses it.
- `OpenApiRouter::routes(routes!(handler))` collects the handler's path metadata and registers the axum method router; `split_for_parts()` returns `(Router, OpenApi)`.
- Only handlers annotated with `#[utoipa::path]` and collected through `routes!` appear in the generated document. A plain `Router` merged alongside contributes routes but no spec.
- `routes!` panics on duplicate method registration for the same path and on CONNECT handlers. Compose each path once.
- Serve the spec from one canonical endpoint such as `/api-docs/openapi.json`, and attach Swagger UI with `.merge(SwaggerUi::new("/swagger-ui").url("/api-docs/openapi.json", ApiDoc::openapi()))`.
- Gate spec and UI exposure separately and per environment. A hidden UI does not make a public JSON spec private.
- Validate or lint the generated document before publishing or using it for codegen, and diff it when it is committed.
- Database rows are not automatically public schemas. Map rows to DTOs before publishing.

## Core Rule

When an Axum API publishes OpenAPI, route changes update the contract in the same change. The document must describe the same requests, responses, status codes, security, and examples that the runtime actually supports.

## Approved Generation Paths

| Repo shape | Preferred path |
|---|---|
| Derive-first, axum-native | `utoipa` derives plus `#[utoipa::path]`, composed manually or with `OpenApiRouter` |
| Router-collected | `utoipa-axum::OpenApiRouter` + `routes!` + `split_for_parts()` |
| Contract crate | A dedicated `openapi` or `contract` module/crate owning the `OpenApi` builder and shared schemas |
| UI only | `utoipa-swagger-ui` merged against the canonical spec endpoint |

Do not switch generators across a whole app unless the user explicitly asked for that migration.

## Folder Structure

```text
src/
├── app.rs
├── openapi.rs          # ApiDoc, shared components, security schemes
├── dto/
│   ├── mod.rs
│   └── user.rs         # ToSchema / IntoParams derives
└── routes/
    └── users/
        ├── mod.rs
        └── handlers.rs # #[utoipa::path] on each public handler
```

- Keep shared components, security schemes, examples, and error envelopes in `openapi.rs` when more than one feature reuses them.
- Keep operation metadata on the handler it documents.
- Compose the canonical document at the app boundary, not by copying fragments by hand.
- Use a stable spec path such as `/api-docs/openapi.json`.
- Serve Swagger UI from a separate path such as `/swagger-ui` or an admin route.

## Operation Metadata Checklist

Every documented operation should define:

- Stable `operation_id`
- Consistent `tag`
- Path params, query params, headers, and request body schemas
- Success responses with status-specific schemas
- Expected error responses such as 400, 401, 403, 404, 409, 422, and 500 when applicable
- Auth requirements through reusable `securitySchemes`
- Request and response examples that match the schema
- Deprecation or hidden metadata when an endpoint should not be public

## Contract Drift Rules

| Drift | Rule |
|------|------|
| Handler accepts input not represented in the document | BLOCKED. Add the parameter/body schema or stop documenting the route. |
| Document lists a status the handler never returns | WARNING. Fix the handler or the document before codegen. |
| Handler returns status-specific payloads but the document shows one generic response | WARNING. Add explicit response schemas. |
| Documented schema exposes raw database rows with internal or sensitive fields | BLOCKED. Add DTO mapping. |
| Shared auth layer exists but the document omits security requirements | BLOCKED for public or partner-facing documents. |
| Swagger UI is public by accident | BLOCKED. Add auth/admin/dev gating or record the public-docs decision. |
| Generated document fails validation or has broken `$ref` values | BLOCKED before publishing. |
| A documented body omits `415` while clients can send an undeclared content type | WARNING. Document the outcome or narrow accepted media types. |
| A body is optional in the document but the handler assumes every field | BLOCKED. Mark the body required or validate the absent case. |

## Example

```rust
use utoipa::{OpenApi, ToSchema};
use utoipa_axum::{router::OpenApiRouter, routes};
use utoipa_swagger_ui::SwaggerUi;

#[derive(ToSchema, serde::Serialize)]
pub struct UserDto {
    pub id: uuid::Uuid,
    pub email: String,
}

#[utoipa::path(
    get,
    path = "/users/{id}",
    tag = "users",
    params(("id" = uuid::Uuid, Path, description = "User id")),
    responses(
        (status = 200, body = UserDto),
        (status = 404, body = crate::error::ErrorBody),
    )
)]
pub async fn get_user(/* ... */) {}

#[derive(OpenApi)]
#[openapi(
    info(title = "API", version = "1.0.0"),
    components(schemas(UserDto, crate::error::ErrorBody))
)]
pub struct ApiDoc;

pub fn documented_router(state: AppState) -> axum::Router {
    let (router, api) = OpenApiRouter::new()
        .routes(routes!(get_user))
        .split_for_parts();

    router
        .merge(SwaggerUi::new("/swagger-ui").url("/api-docs/openapi.json", api))
        .with_state(state)
}
```

## Version and Package Caveats

- Choose the emitted OpenAPI version explicitly. utoipa 6 can emit 3.2, while many codegen consumers still expect 3.0 or 3.1.
- `utoipa-swagger-ui` serves UI assets; it does not generate the document. Its bundled Swagger UI version is independent of the OpenAPI version.
- `routes!` requires `#[utoipa::path]`; a handler without it does not appear in the spec even when it is registered.
- Plain `Router` sub-apps nested under an `OpenApiRouter` may not contribute metadata. Keep documented and undocumented routers clearly separated.
- `operation_id` collisions break client generators; keep them stable and unique.
- Types used in schemas need their utoipa feature enabled, for example `uuid` for `Uuid` and `chrono` for date types. A missing feature shows up as `ToSchema` not implemented.
- Every type referenced in `responses(...)` or `components(schemas(...))` must itself derive `ToSchema`, including the shared error body.
- Do not publish internal error shapes. Use the shared `ErrorBody` type.
- Keep the spec generation deterministic; sort or fix ordering where the generator allows it, and diff committed output.

## Review Checklist

- One generation strategy is used consistently
- Spec endpoint and Swagger UI endpoint are separate and intentional
- Runtime DTOs and documented schemas share a source
- Every documented operation has an `operation_id`, tag, request schema, and error responses
- `routes!` is used only with `#[utoipa::path]` handlers
- Database rows are mapped to public DTOs before publication
- The emitted OpenAPI version is explicit
- Reusable schemas, errors, security schemes, and parameters live in components
- The generated document is validated or linted in CI or locally
- Swagger UI exposure matches the environment policy

## Sources

> Checked 2026-11-05.

| Claim | Source |
|---|---|
| utoipa 6.0.0 features, MSRV 1.88, OpenAPI 3.2 support, version-description inconsistency | [utoipa CHANGELOG](https://github.com/juhaku/utoipa/blob/master/utoipa/CHANGELOG.md), [utoipa docs](https://docs.rs/utoipa/latest/utoipa/) |
| `OpenApiRouter`, `routes!`, `split_for_parts`, duplicate and CONNECT panics | [utoipa-axum](https://docs.rs/utoipa-axum/latest/utoipa_axum/), [OpenApiRouter](https://docs.rs/utoipa-axum/latest/utoipa_axum/router/struct.OpenApiRouter.html) |
| `SwaggerUi::new(...).url(...)` and `.merge(...)` with axum | [utoipa-swagger-ui](https://docs.rs/utoipa-swagger-ui/latest/utoipa_swagger_ui/) |
| `ToSchema`, `IntoParams`, `OpenApi` derive roles | [utoipa docs](https://docs.rs/utoipa/latest/utoipa/) |
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall