Architecting Fullstack

Fullstack SWE Skill

This skill decides the architecture and then hands off to the right specialised skills. It does not repeat what those skills already cover — read them directly for implementation details.

---

Blueprint

Read this skill to decide the architecture pattern and project structure. Then read the specialised skills (building-python-backend, building-sveltekit-frontend, designing-svelte-ui) for implementation details on each layer.

Finally, ask the user if they want you to start coding or explicitly invoke the planning-features skill to write a detailed plan.

Monorepo — Always

Every project is a monorepo. Even if there's only a frontend today, the structure accommodates a backend tomorrow without reorganising. One repo, one agent context, full 360° visibility.

project-root/
├── CLAUDE.md                # Project-level context — read first every session
├── AGENTS.md                # Design system decisions (populated by designing-svelte-ui skill)
├── .github/                 # CI/CD workflows
├── docker-compose.yml       # Local dev: frontend + backend + postgres
├── frontend/                # SvelteKit app
│   ├── package.json         # pnpm as package manager
│   ├── pnpm-lock.yaml
│   ├── svelte.config.js
│   ├── tsconfig.json
│   ├── .env                 # Frontend env vars only — never shares secrets with backend
│   └── src/
│       ├── app.css
│       ├── app.html
│       ├── hooks.server.ts
│       ├── routes/
│       └── lib/
│           ├── api/         # openapi-fetch client + generated schema.d.ts
│           ├── models/
│           ├── services/
│           ├── controllers/
│           ├── factories/
│           ├── stores/
│           └── components/
│               ├── ui/          # shadcn auto-generated
│               ├── primitives/  # Themed wrappers
│               ├── layout/      # Page-level structure
│               └── domain/      # Feature-specific
└── backend/                 # Python FastAPI app — src layout
    ├── pyproject.toml       # Project metadata, dependencies, tool config
    ├── alembic.ini
    ├── .env                 # Backend env vars only
    ├── alembic/
    │   ├── env.py
    │   └── versions/
    ├── tests/
    │   ├── conftest.py
    │   ├── unit/
    │   └── integration/
    └── src/
        └── myapp/           # Replace "myapp" with actual project name
            ├── __init__.py
            ├── app.py       # FastAPI create_app()
            ├── config.py    # AppConfig.from_env()
            ├── factory.py
            ├── errors.py
            ├── dependencies.py
            ├── models/
            │   └── __init__.py
            ├── services/
            │   └── __init__.py
            ├── repositories/
            │   ├── __init__.py
            │   └── orm/
            │       ├── __init__.py  # Imports all ORM models for Alembic
            │       └── base.py      # DeclarativeBase
            ├── controllers/
            │   └── __init__.py
            └── routes/
                └── __init__.py