Design system architecture and data models for development projects

Aria - The Architect is a structural design skill for turning requirements and an implementation plan into a system blueprint. It defines a data model with entities, fields, types, relationships, keys, indexes, constraints, nullability, defaults, and enums. API contracts specify methods, paths, request and response shapes, status codes, authentication, authorization, pagination, filtering, sorting, and error formats.

The blueprint also includes a project directory tree, responsibilities for files and modules, import boundaries, configuration names, and security-sensitive files. It selects backend and frontend patterns when applicable and documents error propagation, logging, observability, and caching. Security architecture covers authentication mechanisms and token lifecycle, authorization models, input validation boundaries, and relevant OWASP Top 10 surfaces. The output format includes an architecture decision record summary, data model, API contract, file structure, security notes, implementation notes, review criteria, and open questions.

Use the skill when a project needs an explicit structural foundation before implementation, especially for schema design, API contracts, module boundaries, or security architecture. Re-invocation for a feature or schema change produces an amendment with a migration note when the database schema changes, rather than rewriting the entire blueprint.

The skill is for design and specification work; its handoff instructions reserve implementation code for the implementation phase. It also calls for resolving vague requirements that could create an ambiguous schema and documenting tradeoffs when multiple patterns are viable. Validate proposed decisions against the actual project requirements and existing schema.

Inputs include the project requirements, an implementation plan, existing schema context, and unresolved design questions. Outputs are concrete decisions and contracts that downstream implementation and review can follow. The data model section can use a structure such as:

Entity: [Name] Fields: - id: uuid, PK, auto-generated - [field]: [type], [nullable/required], [constraints] Indexes: [field(s)] Relations: [entity] via [FK/join table]

For existing systems, the blueprint should note migration strategy and flag N+1 risks, hot-row contention, and full-text or geographic indexing needs. API contracts should specify consistent error envelopes and event payloads when the system is event-driven.

The process works from requirements and implementation plans, and accounts for database, API, frontend, backend, configuration, and security architecture. It can document RESTful or GraphQL naming, MVC, layered, hexagonal, or event-driven patterns, and frontend state approaches when applicable.

Technical leads and software teams can use the blueprint to align architecture, implementation sequencing, and code review expectations before building a system or changing its schema.