Missing/incorrect specification for how blocks are stored in the repo

[aschmahmann]

Checklist

• I am reporting a documentation issue in this repo, not https://docs.ipfs.io.
• I have searched on the issue tracker for my issue.

Location

No response

Description

Currently the only documentation I'm aware of that explains the layout of the go-ipfs repo, and in particular the blockstore, is README that lives inside of FlatFS repos https://github.com/ipfs/go-ds-flatfs/blob/f0750204617b5b0cfb414c38ce486bf9f01963bb/readme.go.

Not only is that the wrong place to put that documentation (since some of it applies regardless of the backing datastore), but it's also incorrect post v0.12.0 and the CID -> multihash migration for the blockstore. We should put a doc in this repo that explains at the very least the blockstore layout if not more generally the repo.

Some of this information lives in ipfs/specs currently although that seems to be the wrong place as it is implementation specific. Examples include https://github.com/ipfs/specs/blob/master/REPO.md and https://github.com/ipfs/specs/blob/master/REPO_FS.md. These may also be very out of date.

Some repo behavior might belong in ipfs/specs (e.g. the API file and corresponding environment variables, or things like #8847), but probably not all of it.