w3auth-architecture

name

w3auth-architecture

description

Architecture guardrails for the W3-Auth wallet-authentication backend. Use this whenever adding or changing code, deciding where new code belongs, naming a package, or considering a new interface, abstraction, Gradle module, dependency, or registry. Apply it before writing the code, not after. Encodes the locked CAIP-10 identity model, the core/infra layer boundaries enforced by ArchUnit, the ephemeral-vs-durable split, and the rule of three. If a request would weaken any of these, push back first.

W3-Auth architecture guardrails

Source of truth is the live repo plus ANTIGRAVITY.md and docs/ANTIGRAVITY_ARCHITECTURE.md. The project-knowledge copies of those docs can lag the repo — when a doc conflicts with the repo or the current conversation, the repo wins, and the drift should be flagged explicitly.

What this backend is

It proves a client controls a wallet private key, then issues a login session. It is protocol-driven, not SDK-driven: every client reduces to (message, signature, accountId). Never import or depend on Reown, WalletConnect, or any wallet SDK — today's mobile client happening to use Reown AppKit changes nothing.

Identity model (locked)

• Identity is CAIP-10: namespace:reference:address.
• The unique key is (namespace, address). Address is identity; chainId is session context. Never key identity on (address, provider, chainId) — that splits one wallet into many identities across EVM chains.
• CaipAccountId canonicalizes (lowercases the EVM address) in its factory. An un-normalized or structurally invalid CaipAccountId must be impossible to construct. Everything downstream speaks CaipAccountId, never raw strings.

Layer boundaries (ArchUnit-enforced)

The core packages — identity, challenge, verification, session, usecase — must not import Spring, JPA, Redis, or infrastructure. Keep them plain Java. Concretely:

• Use cases are plain objects (no @Service). Spring wiring lives only in config (the composition root) and infrastructure.
• JSON/serialization shapes (e.g. a flat record for Redis) live in infrastructure, not in core, so Jackson never leaks into challenge or identity.
• A @Configuration class has one job; don't park an unrelated bean in it.

If a change would make a core package import the framework, that is a boundary break — find the right home for it instead.

Rule of three

Build the first concrete implementation. Do not add an interface, abstraction, module split, or protocol registry until a real second case forces it. The one allowed interface (SignatureVerifier) exists as a test seam, not a future-protocol hook. "We might need it for Solana later" is not justification.

Ephemeral vs durable split

Nonces and challenges live in Redis only, with a TTL, and are never written to Postgres. Wallet identities, refresh tokens, and audit logs live in Postgres, owned by Flyway migrations.

When to actually split a module

Only when a heavy dependency needs isolating (the web3j / RPC client at M3) or when publishing the wire contract as its own artifact. Not before.

Pushback is expected

If a request weakens the architecture — "add a plugin registry now", "put chainId in the identity key", "annotate the use case with @Service", "pull in a wallet SDK for convenience" — say so directly and explain the tradeoff before writing any code. No tutorial/demo shortcuts; production-grade only.