ArchDoc Documentation

ArchDoc Documentation

Intro

ArchDoc offers an easy way for anyone to define their software system in a yaml file (ArchDoc Spec). The archdoc command line tool can then be used to visualize the ArchDoc Spec. The following sections show how you can define ArchDoc Spec files to be consumed by the archdoc command line.

Example

A typical ArchDoc Spec looks like the following:

archdoc: 0.1.0

users:
  user:
    description: "An unauthenticated user."
    dependencies:
      ui: "Reads blog posts and articles"
    documentation: "An unauthenticated user that reads articles."
  editor:
    description: "The admin user of the blog."
    dependencies:
      ui: "Posts blog articles"
    documentation: "The admin user that posts articles."

components:
  ui:
    description: "The frontend application that serves the application users"
    repository: "https://github.com/example/myblogui"
    tags:
      - "frontend"
      - "Next.js"
    dependencies:
      db: "Queries and saves database records"
    documentation: "A frontend application written in Next.js that serves all users to the blog."
  
  db:
    description: "A Postgres database that stores all blog data"
    tags:
      - "database"
      - "Postgres"
    documentation: "A Postgres database that stores entities such as Posts, Users, Comments, etc."

You can find a few other examples in the examples folder in the archdoc-ui repo.

ArchDoc Spec

This is the top level spec for an ArchDoc spec file.

archdoc

Type: string

The version of ArchDoc the spec is written for.

archdoc: 0.1.1

users

Type: object

An object that defines the users that interact with your software system. Each key in the object corresponds to a User Spec object, defined below.

users:
  customer:
    ...
  support-team:
    ...

components

Type: object

An object that defines the services that work together to allow your software system to function. Each key in the object corresponds to a Service Spec object, defined below.

components:
  ui:
    ...
  api:
    ...
  db:
    ...

User Spec

The User Spec defines information about a type of user of your software system. This could be a customer, support person, admin, etc.

description

Type: string

A short description of who the user is and what their needs are.

admin:
  description: A super user

tags

Type: string[]

A list of tags to be associated with the user.

my-user:
  tags:
    - fun
    - smart
    - coffee

dependencies

Type: object

An object describing the services that the user depends on to accomplish their goal.

developer:
  dependencies:
    ui: Uses the web console to deploy resources
    api: Sends HTTP requests to the api to interact with resources

documentation

Type: string

A full, detailed description of the user. Place any extra comments or info about the user here.

my-cat:
  documentation: Even my cat can use this app!

Component Spec

The Component Spec defines information about a component of your software system. This could be an api, frontend app, database, function, object storage bucket, etc.

description

Type: string

A short description of what the service does.

api:
  description: Provides a Public API for all users to enjoy!

tags

Type: string[]

A list of tags to be associated with the service.

my-service:
  tags:
    - dev
    - backend
    - java

repository

Type: string

The URL of the code repository of the service.

my-service:
  repository: https://github.com/ArchDoc/archdoc-ui

dependencies

Type: object

An object describing the other services that this service depends on to accomplish its goal.

ui:
  dependencies:
    api: Provides a Public API to the app backend

documentation

Type: string

A full, detailed description of the service. Place any extra comments or info about the service here.

database:
  documentation: Contains all customer related database tables.