ArchiCat

M²: Modular Mirroring.

ArchiCat is a Gradle-like generative architecture framework for TypeScript.

TypeScript asks: will this import resolve?
ArchiCat asks: should this import exist?

npm i -D archicat

Core rule

dependency graph = import permission graph

A source may import another ArchiCat target only when the dependency graph allows it.

ArchiCat validates:

- unknown dependencies
- self dependencies
- API -> implementation dependencies
- circular dependencies
- cross-target source-path imports

Targets

A module or library has two targets:

module.account.api
module.account.impl
library.backend.api
library.backend.impl

An app is a composition root:

app.main-api

Dependency rules

api  -> api targets only
impl -> own api + declared targets
app  -> declared api/impl targets

Implementation targets are not public by default. They are importable only when declared as dependencies.

Module

import { defineModule } from 'archicat';

export default defineModule({
  name: 'media',

  api: {
    root: './api',
    dependencies: ['module.account.api'],
  },

  impl: {
    root: './impl',
    dependencies: ['module.account.api', 'library.backend.api'],
  },
});

Library

import { defineLibrary } from 'archicat';

export default defineLibrary({
  name: 'backend',

  api: './api',
  impl: './impl',
});

App

import { defineApp } from 'archicat';

export default defineApp({
  name: 'main-api',
  root: './src/app',

  dependencies: [
    'module.media.impl',
    'library.backend.impl',
  ],
});

Imports

Public API:

import { AccountReader } from '@module/account';

Declared implementation dependency:

import { mediaAssembly } from '@module/media/impl';

Blocked without dependency:

import { mediaAssembly } from '@module/media/impl';

Blocked source-path boundary bypass:

import { MediaRepository } from '../../media/impl/repository.js';

Local same-target imports stay normal:

import { dto } from './dto.js';

Config

import { defineArchicatConfig } from 'archicat';

export default defineArchicatConfig({
  typescript: {
    tsConfig: {
      extends: '../../tsconfig.node.json',
      include: ['bootstrap.ts', 'src/app', 'src/libraries', 'src/modules', 'types'],
      exclude: ['node_modules', 'dist'],
    },
  },

  alias: {
    '@app': './src/app/index.ts',
    '@app/*': './src/app/*',
  },

  modules: {
    include: ['./src/modules'],
  },

  libraries: {
    include: ['./src/libraries'],
  },

  apps: {
    include: ['./src/app'],
  },
});

App tsconfig.json:

{
  "extends": "./.archicat/tsconfig.json",
  "compilerOptions": {
    "rootDir": ".",
    "outDir": "./dist"
  }
}

User aliases belong in archicat.config.ts, not in compilerOptions.paths.

Output

.archicat/
  tsconfig.json
  modules/
  libraries/
  types/
  reports/
    build.report.json
    graph.report.json

Commands

archicat build
archicat validate
archicat graph
archicat doctor