CryptoLayer Architecture

BFF + Encrypted Transport + Atomic Design + Clean Layers for Next.js

What is CryptoLayer Architecture?

CryptoLayer Architecture is a frontend architecture pattern for Next.js that enforces:

• 🔐 Encrypted Transport Layer — every payload between your BFF and the browser is encrypted (AES-256-GCM), so credentials and sensitive data never travel in plain text even over HTTPS
• 🏗️ Clean separation of server vs client — services/server/ never reaches the browser bundle; services/cliente/ never touches credentials
• 🧬 Atomic Design for components — atoms → molecules → organisms → templates
• 📐 Layered Clean Architecture — dto / types / schemas / errors / hooks / modules with explicit rules for each layer
• 🧱 Self-contained feature modules — each feature owns its components, hooks, dto, and public API

Quick start

npm install -g cryptolayer-cli
cryptolayer init my-project
cd my-project
npm run dev

CLI commands

| Command | Description | |---|---| | cryptolayer init <name> | Scaffold a new project | | cryptolayer init <name> --no-typescript | Scaffold with JavaScript | | cryptolayer init <name> --skip-install | Skip npm install | | cryptolayer info | Show layer reference in terminal | | cryptolayer --version | Show CLI version |

Architecture overview

src/
├── app/                          # Next.js App Router — pages + API routes only
│   └── api/
│       └── [feature]/
│           └── route.ts          # encrypt() output, handleRouteError()
│
├── modules/                      # Self-contained features
│   └── [feature]/
│       ├── components/           # Organisms specific to this feature
│       ├── hooks/                # ViewModel for this feature
│       ├── dto/                  # API contract for this feature
│       └── index.ts              # Public API — import only from here
│
├── components/                   # Atomic Design — global reusable UI
│   ├── atomos/                   # Button, Input, Badge
│   ├── moleculas/                # FormField, SearchBar, Card
│   ├── organismos/               # Navbar, DataTable, Sidebar
│   ├── plantillas/               # PageLayout, DashboardLayout
│   └── ui/                      # shadcn/ui or MUI generated components
│
├── services/
│   ├── cliente/                  # Client-side fetch + decrypt()
│   └── server/                   # Server-side axios + credentials (never in browser)
│
├── schemas/                      # Zod — runtime validation of API responses
├── dto/                          # External API contracts (Strapi, REST, GraphQL)
├── types/                        # Internal types owned by your app
├── errors/
│   ├── AppError.ts               # Unified error class with code + layer
│   └── errorHandler.ts           # Centralized Next.js route error handler
├── hooks/                        # Shared ViewModels (state + logic, no JSX)
├── context/                      # UI-local state (theme, modals, locale)
├── store/                        # Global business state (auth, user, permissions)
├── utils/                        # Pure functions — cryptoUtil, dateUtil, etc.
├── constants/                    # Fixed values — routes, config, query keys
├── middlewares/                  # Auth guards, rate limiting
├── lib/                          # Third-party client initializations (axios instance)
└── styles/                       # Global CSS, theme tokens

The Encrypted Transport Layer

The defining feature of CryptoLayer Architecture is the encrypted transport between the BFF (Next.js Route Handler) and the browser client.

Client Component
      ↓ calls
services/cliente/featureService.ts  →  decrypt(response.data)
      ↑ HTTPS  (payload is encrypted)
app/api/feature/route.ts            →  encrypt(JSON.stringify(data))
      ↓ calls
services/server/featureService.ts   →  axios with credentials
      ↓ Basic Auth / Token
External API

Encryption guidance

Implement src/utils/cryptoUtil.ts using Node.js built-in crypto module:

| Concern | Recommendation | |---|---| | Symmetric encryption | AES-256-GCM (authenticated encryption) | | HMAC signing | SHA-256 minimum, SHA-512 for sensitive data | | Key material | CRYPTO_SECRET_KEY in .env (server-side only) | | Key rotation | Version prefix in payload: "v1:<iv>:<authTag>:<ciphertext>" | | Key generation | node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" |

⚠️ The CLI generates the interface and guidance for cryptoUtil.ts but does not implement the encryption logic. You must implement it with your own keys. Never commit .env files.

Layer rules

dto/ vs types/

| | dto/ | types/ | |---|---|---| | Defined by | Backend / external API | You | | Shape | As the API returns it (snake_case, string dates) | As your app needs it (camelCase, Date objects) | | Changes when | Backend changes | You decide |

utils/ vs constants/

Has parentheses () → utils/
Is a fixed value   → constants/

encrypt()        → utils/      ✅
ROUTES.HOME      → constants/  ✅

schemas/ purpose

TypeScript validates at compile time. Schemas (Zod) validate at runtime.

// schemas/ catches this — TypeScript cannot:
const result = ExampleSchema.safeParse(response.data);
if (!result.success) throw new AppError('VALIDATION_ERROR', 'Unexpected API shape', 502);

modules/ rule

A module is a self-contained feature. It must:

• Have an index.ts that is the only public export
• Never import from another module directly
• Contain its own components, hooks, and dto specific to that feature

context/ vs store/

context/  →  UI-local state  (theme, open modal, locale)
store/    →  Business state  (auth user, cart, permissions)

Data flow

page.tsx           (View — JSX only)
    ↓ calls
hooks/             (ViewModel — state, effects, no JSX)
    ↓ calls
services/cliente/  (fetch + decrypt)
    ↑ HTTPS
app/api/route.ts   (encrypt + orchestrate)
    ↓ calls
services/server/   (axios + credentials)
    ↓ Basic Auth
External API

Error handling

Every API route uses the centralized handler:

// app/api/example/route.ts
import { handleRouteError } from '@/errors/errorHandler';

export async function GET() {
  try {
    const data = await getFromService();
    return NextResponse.json({ data: encrypt(JSON.stringify(data)) });
  } catch (error) {
    return handleRouteError(error); // always one line
  }
}

Throw typed errors from any layer:

throw new AppError('EXTERNAL_API_ERROR', 'Payment API unreachable', 502, 'server');

Why not MVVM?

MVVM was formalized by Microsoft for WPF in 2005 and relies on two-way data binding. React's model is different:

| Mobile MVVM | CryptoLayer | |---|---| | Model | services/server/ + dto/ + schemas/ | | ViewModel | hooks/ | | View | app/ + components/ | | — | services/cliente/ + utils/cryptoUtil (the Encrypted Transport Layer — has no mobile equivalent) |

CryptoLayer adds the encrypted BFF boundary that does not exist in traditional MVVM.

Contributing

See CONTRIBUTING.md.

License

MIT © Erick Caceres
LinkedIn: erick-cáceres