Index of every page on this site: llms.txt
All skills
suleyman avatar

/fullstack-architect

@920a44a
Run it yourself

Coordinates system-level decisions for production applications built with Next.js, FastAPI, PostgreSQL/PostGIS, Expo, and native iOS, and delegates layer details to the nextjs-frontend, python-fastapi, postgresql, expo-react-native, and swift-ios skills. Use when starting a new product or a feature that spans more than one layer, designing an architecture, choosing how web and mobile share an API, or deciding on authentication, authorization, API contracts, validation, caching, pagination, background jobs, file uploads, observability, migrations, deployment, environments, secrets, scaling, or security.

Use this Skill: https://skilld.dev/gh/suleyman/fullstack-agent-skills/fullstack-architect

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈158 tokens for metadata: the name and description. ≈5.5k when used: this file. ≈5k more on demand in 3 files.

Description uses 7.9% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈631 characters, or 7.9%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Full-Stack Architect

Make the decisions that cross layer boundaries and keep them consistent across every client. Produce an architecture proposal before code, define contracts before UI, then implement vertically using the layer skills.

When to use

  • "Build X" requests that involve more than one of: web, admin, mobile, iOS, API, database.
  • "Where should this logic live?", "How do web and mobile share this?", "How should auth work?"
  • Choosing an approach for uploads, jobs, caching, pagination, realtime, deployment, or environments.
  • Reviewing a design or a PR that changes API contracts, auth, the schema, or the deployment flow.

For changes contained in one layer, use that layer's skill directly.

Skill map

Concern Skill
Web app and admin panel (Next.js, React, shadcn/ui, TanStack Query, Zustand) nextjs-frontend
HTTP API, business rules, auth enforcement, jobs python-fastapi
Schema, constraints, indexes, queries, migrations, PostGIS postgresql
Expo app, EAS Build/Update, push, deep links, permissions expo-react-native
Native iOS, SwiftUI, Keychain, StoreKit swift-ios

Implementation order for a feature: schema and migration → model → request/response schemas → service + endpoint + tests → regenerate client types → web and mobile UI with every state. Finish one vertical slice before starting the next.

Default stack

These decisions are made. Don't re-litigate them without a concrete constraint, and record any deviation and its reason in the architecture doc.

Layer Default Notes
Web and admin Next.js App Router, React, TypeScript, Tailwind CSS, shadcn/ui Frontend + thin BFF. Never touches the database
Mobile Expo + Expo Router + EAS One codebase for iOS and Android
Native iOS Swift + SwiftUI Only when Expo can't meet a stated requirement
Remote state TanStack Query Web and mobile
Local UI state Zustand Only when useState or the URL isn't enough
API FastAPI + Pydantic v2 + SQLAlchemy 2.0 (async) + Alembic The only writer to the database
Database PostgreSQL, + PostGIS when location is a feature Managed, with PITR
Auth OAuth/OIDC sign-in, short-lived JWT access + rotating refresh tokens One identity system
Contracts OpenAPI from FastAPI → generated TypeScript types, Swift Codable Generated, never hand-copied
Jobs Durable Postgres-backed queue (outbox) to start Broker only when throughput demands
Files S3-compatible object storage, presigned direct uploads, CDN API never proxies bytes
Observability Structured logs, OpenTelemetry traces, error tracking on every client Request ID end to end

Workflow

  1. Extract requirements: actors and roles, core entities, the 3–5 critical user flows, which clients exist, scale assumptions (users, peak reads/writes, data growth), regulated or sensitive data (location, payments, health, minors), and non-goals. Ask only about ambiguities that change the architecture (multi-tenant or not, who can see what). State every other assumption explicitly.
  2. Write the proposal with references/architecture-template.md: stack table, component diagram, data model, API surface, auth model, cross-cutting decisions, risks, and delivery slices.
  3. Define the contract for the first slice: resources, request/response schemas, error codes, pagination.
  4. Implement vertically with the layer skills, in the order above.
  5. Update the doc whenever a decision changes. The decision log is part of the deliverable.

System boundaries

  • The API owns the database. FastAPI is the only service that reads or writes Postgres, and the only place business rules and authorization live. Alembic in the API repo is the only thing that changes the schema.
  • Next.js is a frontend and a thin BFF. It renders UI, holds the web session in an httpOnly cookie, and forwards requests to the API with a bearer token. No ORM or database connection in the web app.
  • Mobile and iOS call the API directly with bearer tokens, using the same endpoints as the web.
  • Start with a modular monolith: one API deployable with domain packages inside, plus workers that run the same codebase under a different entrypoint. Extract a service only for a different scaling profile (media processing), a different owner or release cadence, or a hard isolation requirement.

API design

  • REST, resource-oriented, plural nouns, /v1 prefix, JSON.
  • camelCase on the wire, converted once in the API's Pydantic base schema. TypeScript and Swift clients consume it as-is, with no key-transform interceptors.
  • Explicit request and response schemas per operation. Never expose ORM models. Never accept fields the client must not control (owner, role, price, status transitions).
  • IDs: UUIDv7 strings. Never expose sequential integers.
  • Time: ISO 8601 UTC with offset (2026-03-01T10:15:30.123456Z). Dates as YYYY-MM-DD. Never naive datetimes.
  • Money: integer minor units + ISO currency code.
  • Enums: strings. Every client handles unknown values, because mobile binaries outlive enum changes.
  • Evolve additively. Within a version, add optional fields and new endpoints only. Never rename, remove, retype, or newly require a field in place. A breaking change means a new endpoint or version, and the old one is served until the minimum supported app version no longer uses it.
  • Mutations return the updated resource. Non-idempotent creates that clients may retry (orders, payments, messages from flaky networks) accept an Idempotency-Key header.
  • Capabilities over duplicated rules: return flags such as viewerCanEdit so clients don't reimplement authorization.

Shared contracts

  • Source of truth: the OpenAPI document generated from FastAPI's Pydantic models, exported in CI with app.openapi().
  • TypeScript: openapi-typescript generates packages/api-types, imported by web and mobile. openapi-fetch (or a thin fetch wrapper) is the typed runtime client.
  • Swift: Apple's swift-openapi-generator, or hand-written Codable models verified against captured fixtures.
  • CI fails when committed generated types differ from regenerated ones. Breaking-change detection on the OpenAPI diff (e.g. oasdiff) blocks accidental contract breaks.
  • Client form schemas (zod) are UX helpers derived from the contract, never its source.

Repository layout

.
├── apps/
│   ├── web/                 # Next.js (nextjs-frontend)
│   ├── mobile/              # Expo (expo-react-native)
│   └── ios/                 # SwiftUI (swift-ios), only if needed
├── services/
│   └── api/                 # FastAPI + Alembic + workers (python-fastapi, postgresql)
├── packages/
│   └── api-types/           # generated from services/api OpenAPI; never edited by hand
├── infra/                   # docker-compose for local dev, IaC
└── .github/workflows/

Use a monorepo (pnpm workspaces for TypeScript, uv for Python), so an API change, its regenerated types, and the client updates land in one PR.

Authentication

  • One identity system. Either the API issues its own tokens (users table; Google/Apple sign-in verified server-side), or an external IdP (Auth0, Clerk, Cognito, Keycloak) issues them and the API verifies through JWKS. Never both.
  • Access token: a JWT valid for 5–15 minutes, carrying identity only (sub, sid, iss, aud, exp, iat). The API loads the user on each request, so bans and role changes apply immediately.
  • Refresh token: opaque, at least 256 bits of randomness, stored hashed, bound to a session/device, rotated on every use. Reuse of a rotated token revokes the whole session.
  • Web: tokens live in an encrypted httpOnly, Secure, SameSite=Lax cookie (__Host- prefix) owned by Next.js. Browser JavaScript never sees them. Next.js server code attaches Authorization: Bearer when calling the API.
  • Mobile/iOS: access token in memory, refresh token in SecureStore/Keychain (ThisDeviceOnly). Sign-in uses native Sign in with Apple / Google SDKs, or the system browser with PKCE. The ID token goes to the API, which verifies it and issues its own tokens.
  • Logout revokes the server session (and its push registrations) using the refresh token.

Flows, endpoints, tables, and edge cases are in references/auth-flows.md.

Authorization

  • Enforced in the API for every operation. Client checks only shape the UI.
  • Model: roles for coarse access (user, moderator, admin), plus ownership or relationship checks for object-level access.
  • Object-level checks live in the query (WHERE id = :id AND owner_id = :uid, or by tenant). Return 404 for resources the caller can't see.
  • Admin endpoints live under /v1/admin/*, on routers that require a staff role at the router level. Every admin action writes an audit record (actor, action, target, before/after, request ID) in the same transaction.
  • Never trust IDs, roles, prices, or ownership sent by a client.

Validation

Layer Job Tool
Client Fast feedback, fewer round trips zod + React Hook Form; the same rules in mobile forms
API Authoritative input validation and business rules Pydantic schemas, service-layer checks
Database Invariants under concurrency NOT NULL, CHECK, UNIQUE, FK, EXCLUDE

A rule that matters for correctness exists in the API or the database, never only in a client.

Error handling

  • One error body for every endpoint: RFC 9457 Problem Details (application/problem+json) with a stable code, a requestId, and field-level errors for validation failures.
  • Clients branch on code, never on message text. Show the requestId on support-facing error screens.
  • Status semantics: 400/422 = the client can fix it; 401 = re-authenticate; 403/404 = not allowed or not visible; 409 = conflict with current state; 429 = back off (Retry-After); 5xx = server fault.
  • Clients retry only idempotent requests (or ones with an Idempotency-Key), only on network errors, 5xx, or 429, with exponential backoff.

Pagination

  • Cursor (keyset) pagination by default for anything user-generated or growing: ?limit=20&cursor=<opaque> returns { "items": [...], "nextCursor": "..." | null }. Only the server encodes or decodes cursors.
  • Offset/page numbers only for bounded admin tables where jumping to page N is a real requirement. Always cap limit (max 100).
  • No exact totals on large tables. Use nextCursor presence, or approximate counts.

Caching

Each layer has one owner and a stated invalidation path. If you can't say how an entry is invalidated, don't cache it.

  1. CDN/HTTP: static assets, public media, public pages. Authenticated responses are Cache-Control: private, no-store.
  2. Next.js server cache: shared, non-personalized data only ("use cache" + tags), invalidated by tag after admin mutations.
  3. TanStack Query (web and mobile): the primary cache for user data, with staleTime per resource and invalidation on mutation.
  4. Redis: only for measured hot paths, with keys that include every scoping dimension (user, tenant), a TTL, and explicit invalidation on write.
  5. Database: correct indexes and materialized views remove most of the need for 1–4.

Background jobs

  • Slow (more than a few hundred ms), unreliable (third-party calls), or retryable work runs in a worker: push notifications, email, media processing, outbound webhooks, search indexing, exports, account deletion.
  • Enqueue atomically with the business write: an outbox or Postgres-backed job table written in the same transaction. Never "commit, then publish" for work that must happen.
  • Jobs are idempotent (a dedupe key), with timeouts, retries with exponential backoff, a maximum attempt count, and a dead-letter state that alerts.
  • Scheduled jobs take an advisory lock, so replicas don't double-run them.
  • FastAPI BackgroundTasks only for best-effort work you can afford to lose.

File uploads

  1. The client asks the API for an upload: POST /v1/uploads {purpose, contentType, sizeBytes}. The API checks the content type against an allowlist and enforces a size limit per purpose, records a pending upload, and returns a short-lived presigned URL. The object key is generated server-side, never taken from a client filename.
  2. The client uploads straight to object storage. API servers never proxy file bytes.
  3. The client confirms the upload (POST /v1/uploads/{id}/complete), or a storage event fires. The API verifies the object exists and enqueues processing.
  4. The worker checks the real type by magic bytes, strips EXIF/GPS metadata, generates the sizes clients need, and marks the upload ready.
  5. Files are served from a CDN. Private files use short-lived signed GET URLs. Buckets are private, separated per environment, and lifecycle rules delete abandoned pending uploads.

Upload, job-queue, idempotency, and minimum-version recipes are in references/cross-cutting-recipes.md.

Observability

  • Request ID: accepted from a client (validated) or generated, returned in the X-Request-ID header and in error bodies, attached to every log line and to client error reports.
  • Logs: structured JSON, one event per line, with no tokens and no unnecessary PII.
  • Traces: OpenTelemetry for FastAPI, SQLAlchemy, and httpx. Propagate traceparent from Next.js server code to the API.
  • Errors: error tracking (e.g. Sentry) on web client and server, mobile (with source maps for every EAS Update), iOS (dSYMs), API, and workers, tagged by release and environment.
  • Metrics: rate, errors, and p50/p95/p99 duration per endpoint, queue depth and oldest-job age, DB pool saturation, top queries from pg_stat_statements, and for mobile, crash-free sessions per build and update.
  • Alert on symptoms (error rate, latency objectives, queue age), not on causes like CPU.

Migrations and schema changes

  • Run migrations as a separate pipeline step before new code deploys, with a dedicated DDL role. Never on application startup.
  • Expand → migrate → contract. Every migration is compatible with the code currently running. Destructive steps ship in a later release, after no deployed code uses the column and no supported mobile version depends on the API fields behind it. Details: the postgresql skill.

Deployment and environments

Local Staging Production
Database docker compose (PostGIS image, same major versions) Separate managed DB, seeded or anonymized data Managed DB with PITR and a pooler
API + worker docker compose Same image as prod Container replicas, rolling deploy
Web next dev Preview deploys → staging API Production deploy
Mobile Dev client build preview channel and build profile production channel, store builds
Credentials Dev OAuth clients, sandbox push Staging-only credentials Production-only credentials
  • Build once, promote: the same image moves through environments, configured by environment variables.
  • Release order for cross-layer features: expand migration → backward-compatible API → web → mobile update or build → later contract cleanup.
  • Health checks: liveness (process up) and readiness (database reachable). Graceful shutdown on SIGTERM.
  • Rollback paths, documented before the first release: previous image (API), instant rollback (web), eas update:rollback (mobile JS), roll-forward migrations plus a tested restore (database).
  • Non-production environments never touch production data or credentials.

Secrets and configuration

  • Secrets live only in the platform's secret manager or injected env. .env is local-only and gitignored, and .env.example is committed.
  • Anything shipped to a browser or device is public: NEXT_PUBLIC_*, EXPO_PUBLIC_*, Info.plist, app config. Only public identifiers go there (API base URL, error-tracking DSN, publishable keys).
  • Third-party secret keys (payments, storage, push credentials) live only in the API and workers.
  • Every environment has its own credentials. Rotation is a config change, never a code change.
  • Config is validated at startup (pydantic-settings, zod). A missing value stops the process.

Mobile and web API reuse

  • One API serves every client. Resources are client-agnostic.
  • Web-only aggregation goes in the Next.js BFF. Add a screen-shaped endpoint for mobile only when round-trip cost is measured and significant.
  • Every client sends X-App-Version and X-Platform. GET /v1/app-config returns minSupportedVersion per platform, and clients below it show a blocking update screen.
  • Clients are tolerant readers: they ignore unknown fields and handle unknown enum values.

Performance and scaling

Set budgets in the doc (e.g. p95 < 300 ms for core reads) and measure with production-like data. Scale in the order you'll actually need it:

  1. Correct indexes, no N+1 queries, paginated and lean payloads, no client request waterfalls.
  2. Stateless API replicas scaled horizontally, plus a connection pooler sized by pool math.
  3. Slow work moved to workers, scaled by queue depth.
  4. Query tuning, materialized views, denormalized counters.
  5. Read replicas for admin and analytics reads (lag-aware).
  6. Redis caching for measured hot paths.
  7. Partitioning for very large time-series tables.
  8. Service extraction for components with distinct scaling or ownership needs.

Don't start at step 8.

Security baseline

  • OWASP API Top 10: object-level authorization in queries, short-lived tokens with rotation, explicit schemas against mass assignment, rate limits and size limits against resource exhaustion, no server-side fetches of user-supplied URLs without an allowlist (SSRF), and strict CORS with docs disabled in production.
  • Rate limits per IP and per user on sign-in, token refresh, OTP, password reset, uploads, and content creation.
  • TLS everywhere, HSTS on the web, private buckets, least-privilege database roles.
  • Dependency scanning (Renovate or Dependabot, pip-audit, npm audit) and secret scanning in CI.
  • Privacy: collect the minimum. Location is coarse by default. Retention limits are written down. Account deletion removes or anonymizes data across the database, object storage, analytics, and push registrations.

Worked example

Prompt: "Build an event ticketing platform with a Next.js organizer dashboard, FastAPI API, PostgreSQL database, and Expo attendee app."

Layer Decision
Mobile Expo + Expo Router, EAS Build/Update. One app for attendees, plus a door-staff scanning mode. No native iOS app: no requirement Expo can't meet
Web Next.js + shadcn/ui: organizer dashboard (TanStack Query client islands) and public event pages (Server Components, "use cache" tagged per event, revalidated on publish)
API FastAPI modular monolith (auth, events, orders, payments, tickets, checkin) + worker
Database PostgreSQL. No PostGIS: v1 has no location feature, and city filters are enough. Add it when "events near me" becomes a requirement
Remote state TanStack Query. Ticket availability gets a short staleTime and is never cached on the server
Local UI state Zustand only for the scanner session (selected event, offline queue status)
Auth Attendees: Sign in with Apple/Google → API-issued JWT + rotating refresh tokens in SecureStore. Organizers: httpOnly cookie session via the Next.js BFF. Door staff: per-event membership checked in queries
Contracts Pydantic schemas → OpenAPI → packages/api-types for mobile and web
Inventory CHECK (reserved <= capacity) + one conditional UPDATE per ticket type, in ascending ID order. Holds expire through a scheduled job
Payments Stripe with idempotency keys, webhooks deduplicated by event ID, tickets issued by a job after payment. Not in-app purchase: tickets are services used outside the app (App Store guideline 3.1.3(e))
Idempotency POST /v1/orders requires an Idempotency-Key (unique per buyer), so mobile retries can't double-book
Offline QR payloads signed by the API and verified offline by scanners. Check-ins sync in batches, and the server resolves duplicates

Key risks: hot-row lock contention on popular on-sales (split capacity across rows or add a waiting room when measured), double charges (idempotency from client to Stripe), duplicate entry with offline scanners.

Production-readiness checklist

  • An architecture doc records decisions, assumptions, and a decision log.
  • Only the API reads and writes the database. Migrations run as a pre-deploy step.
  • OpenAPI-generated client types, with CI drift and breaking-change checks.
  • Auth: short-lived access tokens, rotating refresh tokens with reuse detection, server-side revocation, platform-appropriate token storage.
  • Object-level authorization is tested for every resource endpoint. Admin actions are audit-logged.
  • Problem Details errors with request IDs from client to database logs.
  • Cursor pagination with capped limits on growing lists.
  • Durable, idempotent jobs with retries and dead-letter alerting.
  • Presigned uploads, private buckets, EXIF stripped.
  • No secrets in repos or client bundles. Per-environment credentials.
  • Logs, traces, and error tracking on every client and service. Alerts on SLO symptoms.
  • Rate limits and request size limits.
  • Minimum supported app version enforced. API changes are additive.
  • Account deletion and privacy disclosures match actual data flows.
  • Rollback is documented and rehearsed for API, web, mobile, and database.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts1mo3 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    The skill provides a comprehensive architectural framework for building full-stack applications with a focus on security best practices, such as OAuth/OIDC integration, token rotation, and secure file handling. No malicious patterns or security risks were identified.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

Signed by skilld at 920a44a. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 2 months ago
metadata
{
  "author": "suleyman",
  "version": "1.0.0"
}

README badge

README badge for suleyman/fullstack-agent-skills/fullstack-architect