In my earlier api designs I’ve arranged the file system hierarchy to match modules much as like what you stated. In my case this resulted lot of sparse directories with on average maybe 3 files per folder. And that caused productivity to drop due increasing navigational burden.

The api design I’m using right now isolates classes on two isolation layers system and engine. The system layer facilitates all common abstractions that you would expect from a modern ‘base class library’ to have think file-io, network-io, memory-streams. The engine layers is what implements the remainder i.e. scene-graphs, world-objects, render-queues.

I go great lengths to adhere a file-structure & naming conventions so the code that is presented to the user is clean and matches the organizational structure as you would find in the Microsoft .NET framework. A small example of that is that I consciously engineer my headers so they are imported as ‘#include <System.IO/BinaryReader.h>’. Folder structure for each isolation layer includes ‘includes’ (.h for public usage), ‘source’ (.cpp), ‘internals’ (.h for private usage) building a sdk type of thing becomes as easy linking everything together and merge the folder structures.

Whether to use interfaces or pimpl is still a case by case decision. This decision is based on how I want people to use the classes. For instance in the case of the binary reader it describes ‘sealed’ functionality. Does it make sense that people could implement their own IBinaryReader or does it make more sense people can use BinaryReader but the class is presented with absence of platform specific code? An extra advantage of the pimple-idiom is that allocation is significantly simplified i.e. it can occur on the stack and doesn’t rely on a factory classes for allocations.

Also to come back on folder replication theres always scripts you can use to automate the tasks. Cp dir1 dir2. Cd dir2. Remove-Files *.* -exclude *.h,*.incl

(I used these techniques for multiple programmers working on one project, but a lot of it applies to distributing an API as well, especially if you give source code access)

Symbolic links and svn externals are your friends here. So is CMake. I was working on a 3 programmer project a while ago, with each programmer working on a discreet layer (graphics, gameplay, and utility) and we didn't have a build server. It took me about 4 days of playing around with cmake to get everything working right, but the investment was well worth it.

The file structure looked like this

src
util
include
src
..
bin
assets
textures
meshes
...


The src directory in svn had externals to bin and assets, so someone checking out src automatically got those checked out.

CMake then did several things:
1. Automatically detect install paths for DX, OGL, and other programs such as Maya / 3ds Max (if the user was compiling things that needed them) and added them to the generated projects / makefiles. If a directory wasn't found through standard system / environment variables, the uses had the option of adding them manually.
2. Make a symlink to assets in the build directory.
3. Add pre-build events to copy binaries out of src/bin to bld/Debug and bld/Release (for VS).
4. Add post-build events to copy binaries out of bld/Debug and bld/Release to src/bin

The last two were done because we did not have a build server, and each programer didn't want to compile the code in the levels below the one they were working at. So if util and graphics were changed and compiled by the people working on them, after they made a commit, the game programmer would update and get new binaries without needing to build them or having the projects to be added to their own build. I used old fashioned copying rather than a symlink like with assets for two reasons: we wanted to keep the VS standard of compiling to /Debug and /Release, but we wanted to have one unified bin directory in the svn; and we didn't want to pollute the bin directory with all the VS specific files generated, and at the same time we didn't want to delete them because they were useful.