Repository structure with Megamono and Nx

A repository should explain what its code is for before you open a manifest. The useful distinction is not TypeScript versus Rust versus Swift. It is an application you run, an implementation you share internally, or a package other repositories consume.

Use this layout to understand where new code belongs. Existing repositories can keep their established folders; adopting Megamono does not require reorganizing everything.

The three main homes

#

Distribution can be public or private. A package shared with one other company repository still has an external consumer and a compatibility contract.

workspace/
├── apps/
│   ├── site/                 # Marketing and documentation
│   ├── web/                  # Product dashboard
│   ├── api/                  # Backend application
│   ├── extension-grids/      # One browser extension
│   ├── extension-guides/     # Another browser extension
│   ├── android/              # Native Kotlin application
│   └── macos/                # Native Swift application
├── libs/
│   ├── theme/                # This product's shared branding
│   ├── invoicing/            # Repository-owned domain logic
│   └── rust-core/            # Internal Rust implementation
├── packages/
│   ├── typescript-sdk/       # Published JavaScript/TypeScript API
│   ├── rust-sdk/             # Distributable Cargo crate
│   └── swift-sdk/            # Distributable Swift package
├── docs/                     # Repository governance and decisions
│   ├── specs/                # Intended behavior, grouped by project
│   ├── plans/                # Work to deliver it, grouped by project
│   ├── decisions/            # Choices and their rationale
│   ├── research/             # Investigations and evidence
│   ├── audits/               # Evaluation against a stated standard
│   ├── reports/              # Dated observations with retention
│   ├── design/               # Tokens, boards, screenshots, and visual handoffs
│   ├── archives/             # Historical specs, plans, and research
│   ├── DESIGN.md             # Repository-owned design direction
│   └── INDEX.md              # Generated index of the active corpus
├── tools/                    # Repository maintenance tooling
├── AGENTS.md                 # Repository instructions and reading order
└── nx.json                   # Nx workspace configuration

This is an illustrative layout, not a list of required projects. Do not create empty layers simply to match it.

Keep application-specific code close

#

Start inside the application when code has one owner and no useful independent boundary. An API's home controller can live under apps/api/src/app/; it does not need a separate nest-home library merely because it can be extracted.

Extract to libs/ when there is a meaningful reason: reuse between applications, a cohesive domain boundary, separate tests, or clear ownership. A library can be useful even with one consumer, but every function and component does not need its own Nx project.

For example, a theme shared by the site and dashboard belongs in libs/theme. If that theme becomes a supported design system for other repositories, it becomes a candidate for packages/. That decision changes the consumption contract, not just the folder name.

A workspace package is not necessarily distributable

#

An internal library may still have a package.json, a package name, exports, and workspace dependencies. Those can support local resolution and clear boundaries without making it a registry product.

For npm-compatible publishing, private: true means do not publish. It does not mean publish to a private registry. A privately distributed package needs explicit registry and access configuration, with credentials kept outside committed source.

Before publishing a package, define its entry points, built files, dependencies, and versioning. Test it from another project. Moving code into packages/ does not publish it or configure a registry. See library options to create an internal or publishable TypeScript library.

What Nx contributes

#

Nx models projects, their dependencies, and the tasks that build, test, and check them. Folder names are organizational conventions, not the project graph itself. Nx supports different layouts and project configuration through package manifests, project configuration, and applicable plugins. See Nx's workspace guide.

Megamono adds repository conventions, classification, generation, and governance alongside that machinery. Use project tags to describe dimensions such as platform, scope, and role; configure boundary checks to enforce the intended relationships. A directory name alone does not enforce them. Nx's folder-structure guidance also treats layout as a convention rather than a requirement.

As a starting policy, applications compose libraries and packages. Internal libraries should not import application internals. Distributable packages must not leave consumers depending on unpublished workspace-only code: publish the dependency too, or deliberately include it in a qualified distribution artifact. Avoid dependency cycles in either direction.

Rust, Swift, and other ecosystems

#

Native Kotlin apps belong in apps/ too. The Android preset defaults to apps/android, keeps Gradle in charge of the native build, and exposes tasks through Nx. It is separate from the Expo mobile preset; there is no need for a top-level kotlin/ directory simply because the language differs.

Do not add top-level cargo/ or swift/ directories solely because another language appears. A Swift app belongs in apps/; an internal Rust library belongs in libs/; a distributable crate belongs in packages/ under this convention.

Keep native structures where their tools expect them. A Tauri application's Rust code can remain within that application. Configure Cargo workspace membership and Swift package dependencies explicitly; placing files in a folder does not establish those relationships. Native build, test, signing, and release requirements still apply.

Use the platform plugin reference to inspect supported inference. Do not assume JavaScript import checks validate every native dependency or that one ecosystem's release workflow works for another.

Moving between libs and packages

#

Promotion from libs/ to packages/ should be an explicit, reviewed change: establish the distribution contract, update paths and consumers, configure builds and release ownership, then test the packed artifact in a consumer.

Demotion from packages/ to libs/ should remove future publishing, update references, and account for external consumers. It does not unpublish existing releases or erase compatibility obligations.

Both directions require ecosystem-specific handling of imports, workspace membership, TypeScript or native project references, task inputs and outputs, and dependencies. Review a plan and verify the resulting graph before merging.

For new TypeScript code, use the library generator to choose an internal or publishable library. For existing code, moving a directory alone is not enough: update imports, package exports, project configuration, and release settings together, then run builds and consumer tests. Do not assume an automatic two-way migration is available. Existing private libraries remain internal even if their directory is named packages/.

The docs directory: the repository's memory

#

docs/ helps maintainers and agents understand what should exist, why choices were made, what is underway, and what has actually been verified. These records are readable Markdown; understanding the repository should not require starting an application or building a website.

Choose the folder by the question the document answers, not by who wrote it:

Use exact Nx project names for project ownership and the generated project directories for specs and plans. A spec describes the intended system; a plan tracks the work to achieve it. Research records evidence; a decision records a choice. An audit judges evidence against a standard; a report records observations. Those distinctions keep an exploratory note from accidentally becoming an accepted requirement.

Indexes, design direction, and agent instructions

#

Start at docs/INDEX.md to find the relevant specs, decisions, and in-progress plans. It is a generated index of the active corpus, not another document to maintain by hand. Archives have their own index; reports are excluded from the default index so repeated check output does not bury current context.

docs/DESIGN.md holds the repository's design direction: typography, spacing, visual influences, and explicit things to avoid. Root-level AGENTS.md tells contributors and agents what to read, where to place work, and which commands and conventions to use. It should point to the authoritative records, not duplicate their contents.

Visual design handoffs

#

Keep the detailed visual references in docs/design/ alongside that brief:

docs/design/
├── README.md       # How to use the handoff and which sources are authoritative
├── manifest.md     # Maps visual references to specs, states, and acceptance tests
├── boards/         # Editable mockups and measurement references
└── screenshots/    # Visual targets and implementation comparisons

The docs scaffold seeds this structure without replacing existing files. You can add tokens.json for shared design values, but first declare whether it is the source of truth or an export from your existing theme. Megamono does not invent token values or generate a second theme. For larger repositories, group assets under docs/design/<project>/.

Specs define behavior; boards and screenshots illustrate it. Flag disagreements instead of silently changing requirements. In the manifest, identify sample content, target versus actual captures, platform/theme variants, viewport sizes, and capture dates. Mockup HTML is a reference, not a requirement to port its component structure to native applications.

Design assets are repository-owned supporting material, not another lifecycle document type. They need no spec-style frontmatter, are not automatically published, and are not archived or pruned by the document lifecycle commands. The active docs index links to the handoff README when it exists. Keep screenshots sanitized and document any token-generation or visual-comparison workflow you add.

Keep current context separate from history

#

Specs evolve as the intended system changes. Plans remain active while they are in the backlog, in progress, or on hold. Complete or abort a plan through the archive action, which updates its lifecycle metadata and moves it into docs/archives/plans/<project>/. Record why an aborted approach was abandoned so it is not proposed again without that context.

Archives are not a general-purpose dumping ground. They mirror specs/, plans/, and research/ for eligible lifecycle transitions. Decisions and audits stay in their original folders; a replacement record declares what it supersedes. Reports use retention and the reviewed report-pruning action, not archival.

Keep stable document IDs and metadata for type, status, visibility, projects, topics, and summary. Use those IDs in repository-document references so relationships survive moves. Prefer the documentation generators and lifecycle tools for creation, validation, indexing, and archival instead of manually inventing filenames or moving records without updating their metadata.

Repository docs are not public product content

#

Repository governance is internal by default. Public how-to guides, API documentation, changelogs, and other product content belong to their consuming application or content library—for example, apps/site/content/docs/ or libs/content/. They can use their own schemas and publishing lifecycle rather than pretending every article is a repository specification.

An internal decision may cite a public guide. Public content should not depend on internal repository documents or link readers to private implementation notes. Publishing governance material requires explicit visibility review and a public-only content boundary; a Markdown file's presence in the repository does not authorize publishing it.

Keep secrets and credentials out of both corpora. Treat generated site output, search caches, and build artifacts separately from authored documents. When adopting an existing corpus, preserve its accepted statuses, stable references, and ownership through reviewed mappings rather than recasting everything as a new draft.

Adopting an existing repository

#

Keep established crates/, swift/, src/, or other layouts when they already express ownership well. Classify the existing projects and review their dependencies before considering relocation. Adoption should not move code, rewrite imports, or take over release policy just to match this example.

Start with a write-free adoption survey. Keep internal governance documents separate from application content: public site docs can remain in the site's content directory, and build outputs and local caches should stay out of source control according to their owners' rules.

When in doubt, ask: Who consumes this code, and what contract do we owe them? Let that answer determine its home.