Flisk Layout

---
name: flisk-layout
description: Decide where a Flisk project lives when services span several repositories or teams - one platform repo with bring-your-own services versus one project per service repo - plus name and port clashes between projects, CODEOWNERS for service.json files, and layouts for about 5, 20 and 50 services. Use when planning project structure or onboarding a team. For adding one service, use flisk-scaffold or flisk-byo.
license: MIT
compatibility: Requires the flisk CLI. Does not deploy.
metadata:
  author: flisk-sh
  version: "1.0"
---

# Layout and ownership

One Flisk project is one repository tree: the CLI finds services by walking the project directory for `service.json` files.

## Workflow

1. Pick a layout:
   - **One platform repo:** one `.flisk/project.json`, a `service.json` per service. Code that lives in another repo is wrapped as a bring-your-own resource, from a registry `image` or from a sibling checkout via `buildContext`.
   - **One project per service repo:** the ordinary single-repo flow. Each team keeps its files, at the cost of one Postgres and one Traefik per project on the same default host ports.
2. Keep every `service.json` inside the project root. A `service.json` outside it, or a `discovery.paths` entry pointing into another repo, is not supported (the CLI and Tilt disagree and generation is refused). Symlinked directories are not followed.
3. Group services into stacks by team or domain, so `flisk up <stack>` starts only what one team needs.
4. Ownership: give `.flisk/project.json` to the platform team in `CODEOWNERS`, and each stack's `services/<stack>/` to its team.
5. Agent guidance: `flisk project` writes an `AGENTS.md` and the Flisk skills into the project. For an existing repo, start from the [landscape template](https://raw.githubusercontent.com/flisk-sh/flisk-skills/main/rules/AGENTS.landscape.md) and add only repo-specific rules.

## Name and port clashes

- Two projects on one Docker daemon need different project names; containers are named `<project>-<stack>-autogenerated-<service>-1`.
- The same `appName` twice in one project fails `flisk doctor` with `Duplicate resource names`.
- Two services with the same `port` only warn, because service ports are not published on the host.

## Guardrails

- Install the skills once per machine or project; do not copy the catalog into every service repo.
- Keep `service.json` the single source of truth; never edit generated files to make a layout work.
- Guide, including the 5, 20 and 50 service layouts: [docs/layout.md](https://github.com/flisk-sh/flisk/blob/main/docs/layout.md).