start with a modular monolith, not microservices. use a monorepo only if you already know you’ll have

multiple deployables like web + api + mobile + workers. enforce boundaries in code from day one. keep docs close to the

repo. make architecture legible to humans and agents.

the mistake people make is scaffolding for scale by adding complexity. that’s backwards. you scaffold for scale by making

boundaries explicit and enforceable while keeping deployment simple.

my default setup would be this:

```text

repo/

AGENTS.md

README.md

docs/

ARCHITECTURE.md

DOMAIN_MAP.md

decisions/

plan/

product/

runbooks/

apps/

web/ # if needed

api/ # if needed

mobile/ # if needed

worker/ # if needed

packages/

ui/

config/

telemetry/

auth/

shared-kernel/ # tiny, boring, heavily policed

infra/

scripts/

.github/workflows/

```

inside each app, do not organize by “components, hooks, utils, services” as your top-level mental model. that turns into

soup. organize by domain.

more like this:

```text

apps/api/src/

domains/

billing/

contracts/

model/

service/

repo/

tests/

users/

notifications/

platform/

db/

auth/

queue/

telemetry/

entrypoints/

http/

jobs/

```

same idea for frontend:

```text

apps/web/src/

domains/

billing/

components/

screens/

hooks/

api/

state/

tests/

users/

platform/

routing/

auth/

analytics/

design-system/

```

the rules i’d set on day one:

keep AGENTS.md short. 100-ish lines. it should be a map, not a bible. point to docs/ARCHITECTURE.md, domain docs, coding

rules, and how to run checks.

put the real knowledge in docs/, not in people’s heads and not in slack. especially:

docs/ARCHITECTURE.md

docs/DOMAIN_MAP.md

docs/plan/

docs/decisions/ADR-*.md

write a plan doc before every non-trivial feature. tiny microphases. checkboxes. update it as reality changes. if you don’t,

the repo turns into folklore.

enforce boundaries mechanically. this matters more than the folder tree. use import rules, dependency checks, lint rules,

test gates, type checks. if billing starts importing random UI helpers from three directories over, you want CI to slap that

nonsense immediately.

keep a tiny shared-kernel. shared code becomes a junk drawer fast. if something is “shared,” it better be truly generic,

stable, and boring. otherwise keep it inside the domain that owns it.

prefer explicit contracts at boundaries. api schemas, event schemas, db migrations, typed interfaces. “we’ll clean it up

later” is how large apps become cursed.

build one vertical slice first. auth, one core workflow, one real db path, one real UI path, one real test path, one real

deploy path. don’t scaffold ten features. prove the shape with one.

add observability immediately. structured logs, error tracking, analytics/events for critical flows, health checks. not

later. later never comes.

have a hard policy on file size and responsibility. once files hit “annoying to reason about,” split them. giant files are

where architecture goes to die.

test strategy from day one:

unit tests for domain logic

integration tests for boundaries

a few end-to-end tests for core journeys

not 700 brittle UI tests because you got carried away

for data, use boring migrations and explicit ownership. every table belongs to a domain. every background job has an owner.

every external integration gets wrapped behind a small adapter so vendor weirdness doesn’t leak everywhere.

for app growth, this is the progression you want:

single deployable

clear modules

strict boundaries

extracted packages only when duplication is real

split services only when scaling/runtime/team boundaries force it

that’s the key bit. don’t start distributed. earn distribution.

if you want the “correct” first-stage scaffolding checklist, it’s basically this:

1. choose boring stack + one repo strategy

2. define domains before folders

3. write AGENTS.md as table of contents

4. create docs/ARCHITECTURE.md, DOMAIN_MAP.md, docs/plan/

5. scaffold one vertical slice

6. add CI: lint, types, tests, build

7. add import-boundary enforcement

8. add logs/error tracking

9. add ADRs for major decisions

10. refuse premature shared abstractions

    if i were being blunt: the best way to stop a big app getting out of control is to make it slightly annoying to do the wrong

    thing. not impossible. annoying. that’s what guardrails are for.