---
name: replica-architect
description: >-
  Plans the stack, database schema and API for an app clone, from the recon map replica-recon wrote. Picks boring, managed tech, turns the inferred data model into real SQL with indexes and access rules, lists every route by flow, and orders the build as a thin vertical slice first. Use when the user says "plan the clone", "what stack should I use", "design the database", "write the schema", "plan the API", "architecture for my version of X", or after /replica-recon finishes.
title: replica-architect
canonical_url: https://skilld.dev/gh/jakeschincariol/replica-skill/replica-architect
last_updated: 2026-10-05T17:02:13.000Z
---

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [architecture.md](https://skilld.dev/api/skills-raw/jakeschincariol/replica-skill/replica-architect/architecture.md).
>
> If the user asked to install this Skill, run `npx skilld install jakeschincariol/replica-skill/replica-architect`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/replica-architect`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jakeschincariol/replica-skill/replica-architect) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/replica-architect`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/replica-architect --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/replica-architect --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# replica-architect

Reads `replica/recon.md` and `replica/features.csv`. Writes
`replica/architecture.md` (template: architecture.md in this folder).

If there is no recon map, stop and run `/replica-recon` first. Planning a
clone from memory of what an app does is how you miss half of it.

## Step 1: the stack

Use what the user already knows if they have a stack. Otherwise the default,
because every part is managed, documented and cheap at zero users:

| layer | default | swap for |
| --- | --- | --- |
| web app | Next.js (App Router) + TypeScript | Remix, SvelteKit, Rails |
| styling | Tailwind, tokens from replica-design | CSS modules |
| mobile | Expo (React Native) | SwiftUI, Kotlin |
| database | Postgres on Supabase or Neon | PlanetScale, SQLite (Turso) |
| ORM | Drizzle or Prisma | raw SQL |
| auth | Supabase Auth or Auth.js | Clerk |
| payments | Stripe Checkout + Billing | Lemon Squeezy, Paddle |
| email | Resend or Postmark | SES |
| jobs | Vercel Cron, Inngest or Trigger.dev | a worker on Fly |
| files | Supabase Storage or Cloudflare R2 | S3 |
| hosting | Vercel | Netlify, Fly, Render |

Write each choice with one line of why. One database. No microservices. The
clone does not need the original's architecture, it needs the original's
features.

## Step 2: the schema

Turn the inferred data model into SQL. For every table:

- `id uuid primary key default gen_random_uuid()`, `created_at`, `updated_at`
- an owner column (`user_id` or `org_id`) on everything a user owns
- foreign keys with an `on delete` rule decided, not defaulted
- indexes on every foreign key and every column you filter or sort by
- enums or check constraints for status fields
- times as `timestamptz`, always, stored in UTC
- money as integer cents plus a currency column
- access rules: Postgres row level security on Supabase, or one
  authorisation check per query in the data layer. Write which.

Example, for a booking app:

```sql
create table bookings (
  id uuid primary key default gen_random_uuid(),
  event_type_id uuid not null references event_types(id) on delete cascade,
  host_id uuid not null references users(id) on delete cascade,
  start_at timestamptz not null,
  end_at timestamptz not null,
  guest_name text not null,
  guest_email text not null,
  guest_timezone text not null,
  status text not null default 'confirmed'
    check (status in ('confirmed','cancelled','rescheduled')),
  answers jsonb not null default '{}',
  created_at timestamptz not null default now(),
  constraint no_zero_length check (end_at > start_at)
);
create index on bookings (host_id, start_at);
```

Then the hard constraints the recon found. Two guests booking the same slot
is a database problem (an exclusion constraint or a unique index), not a UI
problem.

## Step 3: the API

One table per flow from the recon map. For every route or server action:

`method path | what it does | who can call it | input | output | flow`

Plus webhooks in (Stripe, calendar providers) and out, and background jobs
(reminders, sync, cleanup) with their schedule.

Only official, public APIs with the user's own keys. Never the original app's
private endpoints, even if they are visible in a browser.

## Step 4: the parts that bite

Write a line on each that applies: time zones and daylight saving, idempotency
(webhooks arrive twice), race conditions, rate limits, file size limits,
search, realtime, offline, email deliverability, multi-tenancy, GDPR deletion.

## Step 5: build order

1. **Vertical slice.** The core loop end to end, ugly: sign up, do the one
   thing, see the result. Proves the stack.
2. **Must-haves** from `features.csv`, by area.
3. **Should-haves**, then could-haves.
4. **The fixes** replica-entrepreneur finds, once it has run.

Each milestone lists its screens (S-IDs), tables and routes.

## Output

`replica/architecture.md`, the SQL in `replica/schema.sql` or as the first
migration, and a summary: stack in one line, table count, route count, the
three riskiest parts, and the next step: `/replica-design`.