Project Structure

When you run arckit init, ArcKit creates a well-organized directory structure designed for enterprise architecture governance. This structure separates global artifacts (shared across all projects) from project-specific deliverables, and provides dedicated locations for templates, scripts, and AI assistant commands.

Directory Tree

payment-modernization/
├── .arckit/
│   ├── scripts/
│   │   └── bash/                          # Automation scripts
│   ├── templates/                         # Default templates (refreshed by arckit init)
│   └── templates-custom/                  # Your customizations (preserved across updates)
├── projects/
│   ├── 000-global/
│   │   ├── ARC-000-PRIN-v1.0.md           # Global architecture principles
│   │   ├── policies/                      # Organization-wide policies
│   │   └── external/                      # External policy documents (PDFs, images)
│   └── 001-payment-gateway/
│       ├── ARC-001-PLAN-v1.0.md           # Project plan with Gantt chart
│       ├── ARC-001-STKE-v1.0.md           # Stakeholder analysis
│       ├── ARC-001-RISK-v1.0.md           # Risk register (Orange Book)
│       ├── ARC-001-SOBC-v1.0.md           # Strategic Outline Business Case
│       ├── ARC-001-REQ-v1.0.md            # Comprehensive requirements
│       ├── ARC-001-PLAT-v1.0.md           # Platform strategy (optional)
│       ├── ARC-001-DATA-v1.0.md           # Data model with ERD, GDPR compliance
│       ├── ARC-001-DPIA-v1.0.md           # Data Protection Impact Assessment
│       ├── ARC-001-DSCOUT-v1.0.md         # Data source discovery
│       ├── ARC-001-RSCH-v1.0.md           # Technology research
│       ├── wardley-maps/                   # Strategic Wardley Maps
│       │   ├── ARC-001-WARD-001-v1.0.md   # Current architecture positioning
│       │   ├── ARC-001-WARD-002-v1.0.md   # Target architecture vision
│       │   ├── ARC-001-WARD-003-v1.0.md   # Gap analysis
│       │   └── ARC-001-WARD-004-v1.0.md   # Build vs buy decisions
│       ├── ARC-001-ROAD-v1.0.md           # Strategic roadmap
│       ├── ARC-001-STRAT-v1.0.md          # Architecture strategy synthesis
│       ├── decisions/                      # Architecture Decision Records
│       │   ├── ADR-001.md                 # Database selection
│       │   ├── ADR-002.md                 # Authentication approach
│       │   └── ADR-003.md                 # Cloud provider choice
│       ├── ARC-001-SOW-v1.0.md            # Statement of Work (RFP)
│       ├── ARC-001-DOS-v1.0.md            # Digital Outcomes & Specialists (UK)
│       ├── ARC-001-GCLD-v1.0.md           # G-Cloud service search (UK)
│       ├── ARC-001-GCFY-v1.0.md           # G-Cloud clarification questions (UK)
│       ├── ARC-001-EVAL-v1.0.md           # Vendor evaluation framework
│       ├── vendors/
│       │   ├── acme-corp/
│       │   │   ├── proposal.pdf
│       │   │   ├── scoring.md
│       │   │   ├── hld-v1.md              # Vendor's High-Level Design
│       │   │   └── reviews/
│       │   │       └── hld-v1-review.md   # ArcKit HLD review
│       │   ├── beta-systems/
│       │   │   ├── proposal.pdf
│       │   │   ├── scoring.md
│       │   │   ├── hld-v1.md
│       │   │   ├── dld-v1.md              # Vendor's Detailed Design
│       │   │   └── reviews/
│       │   │       ├── hld-v1-review.md
│       │   │       └── dld-v1-review.md   # ArcKit DLD review
│       │   └── comparison.md
│       ├── diagrams/                       # Architecture diagrams
│       │   ├── ARC-001-DIAG-001-v1.0.md   # C4 Context diagram
│       │   ├── ARC-001-DIAG-002-v1.0.md   # C4 Container diagram
│       │   ├── ARC-001-DIAG-003-v1.0.md   # Deployment diagram
│       │   └── ARC-001-DIAG-004-v1.0.md   # Data flow diagram
│       ├── ARC-001-BKLG-v1.0.md           # Product backlog (Markdown)
│       ├── ARC-001-BKLG-v1.0.json         # Product backlog (JSON for Trello)
│       ├── ARC-001-BKLG-v1.0.csv          # Product backlog (CSV for Jira)
│       ├── ARC-001-SNOW-v1.0.md           # ServiceNow service design
│       ├── ARC-001-DVOP-v1.0.md           # DevOps strategy
│       ├── ARC-001-MLOP-v1.0.md           # MLOps strategy (AI projects)
│       ├── ARC-001-FNOP-v1.0.md           # FinOps strategy
│       ├── ARC-001-OPS-v1.0.md            # Operational readiness
│       ├── ARC-001-TRAC-v1.0.md           # Traceability matrix
│       ├── ARC-001-ANLZ-v1.0.md           # Governance quality analysis
│       ├── ARC-001-PCOM-v1.0.md           # Principles compliance assessment
│       ├── ARC-001-CONF-v1.0.md           # Conformance assessment
│       ├── ARC-001-SVCA-v1.0.md           # Service Assessment (GDS)
│       ├── ARC-001-TCOP-v1.0.md           # Technology Code of Practice
│       ├── ARC-001-SCUR-v1.0.md           # Secure by Design
│       ├── ARC-001-AIPB-v1.0.md           # AI Playbook compliance
│       ├── ARC-001-ATRS-v1.0.md           # ATRS record
│       ├── ARC-001-STORY-v1.0.md          # Project story
│       ├── ARC-001-PRES-v1.0.md           # MARP presentation
│       ├── external/                       # External documents (PDFs, images)
│       │   ├── existing-architecture.pdf
│       │   ├── network-diagram.png
│       │   └── compliance-report.docx
│       └── final/
│           ├── selected-vendor.md
│           ├── approved-hld.md
│           └── dld/
├── .codex/                                # Codex CLI (if --ai codex)
│   ├── prompts/                           # Slash command prompts
│   │   ├── arckit.plan.md
│   │   ├── arckit.principles.md
│   │   ├── arckit.requirements.md
│   │   └── ... (54 commands)
│   ├── README.md
│   └── .gitignore
├── .opencode/                             # OpenCode CLI (if --ai opencode)
│   ├── commands/                          # Slash commands
│   │   ├── arckit.plan.md
│   │   ├── arckit.principles.md
│   │   ├── arckit.requirements.md
│   │   └── ... (54 commands)
│   ├── agents/                            # Specialized agents
│   │   ├── research.md
│   │   ├── datascout.md
│   │   └── azure-research.md
│   ├── skills/                            # Reusable skills
│   ├── opencode.json                      # MCP server configuration
│   ├── README.md
│   └── .gitignore
├── docs/                                  # Documentation (unless --minimal)
│   ├── guides/                            # Command guides
│   │   ├── principles.md
│   │   ├── requirements.md
│   │   └── ... (command-specific)
│   └── README.md
├── DEPENDENCY-MATRIX.md                   # Command dependency structure
├── WORKFLOW-DIAGRAMS.md                   # Workflow visualizations
├── VERSION                                # ArcKit version
├── CHANGELOG.md                           # Release notes
├── README.md                              # Project README
├── .envrc                                 # direnv configuration
└── .gitignore                             # Git ignore rules

Key Directories

`.arckit/`

Contains ArcKit infrastructure:

.arckit/templates/

Default templates for all ArcKit commands. These are refreshed when you run arckit init to update your project.Do not edit directly - use .arckit/templates-custom/ instead.Example templates:

project-plan-template.md
architecture-principles-template.md
requirements-template.md
risk-register-template.md
data-model-template.md

.arckit/templates-custom/

Your customized templates that persist across arckit init updates.Use /arckit.customize to copy templates here for editing:

/arckit.customize requirements    # Copy requirements template
/arckit.customize all             # Copy all templates
/arckit.customize list            # See available templates

Commands automatically check this directory first before falling back to .arckit/templates/.See Template Customization for details.

.arckit/scripts/bash/

Automation scripts used by ArcKit commands:

check-prerequisites.sh - Validates project structure
generate-filename.sh - Creates ARC-formatted filenames
find-project.sh - Locates project directories

Used internally by commands; typically not invoked directly.

`projects/`

Contains all architecture governance artifacts:

projects/000-global/

Global artifacts shared across all projects:

ARC-000-PRIN-v1.0.md - Architecture principles (foundation for all design reviews)
policies/ - Organization-wide policies (security, data governance, compliance)
external/ - External policy documents (PDFs, images, Word docs)

Project ID 000 is reserved for global artifacts.Commands like /arckit.principles always write to 000-global/.

projects/{NNN}-{project-name}/

Project-specific artifacts numbered sequentially:

001-payment-gateway/
002-customer-portal/
003-data-warehouse/

Each project directory contains:

Core documents: PLAN, STKE, RISK, SOBC, REQ, DATA, DPIA, etc.
Subdirectories: wardley-maps/, decisions/, diagrams/, vendors/, external/, final/
Multi-version support: Documents use v1.0, v1.1, v2.0 suffixes

See Filename Conventions below.

`.codex/` or `.opencode/`

AI assistant-specific directories (created based on --ai flag):

.codex/ (Codex CLI)

For OpenAI Codex CLI users:

.codex/prompts/ - 54 slash command prompts (e.g., arckit.principles.md)
.codex/README.md - Codex-specific setup instructions
.envrc - Sets CODEX_HOME="$PWD/.codex" for direnv

Commands are invoked as:

/prompts:arckit.principles Create principles for financial services

.opencode/ (OpenCode CLI)

For OpenCode CLI users:

.opencode/commands/ - 54 slash commands (e.g., arckit.principles.md)
.opencode/agents/ - Specialized research agents
.opencode/skills/ - Reusable skills (Wardley Mapping, Mermaid syntax)
.opencode/opencode.json - MCP server configuration (AWS, Azure, Google)
.envrc - Sets OPENCODE_HOME="$PWD/.opencode" for direnv

Commands are invoked as:

/arckit.principles Create principles for financial services

Filename Conventions

ArcKit uses a consistent naming pattern for all artifacts:

Document ID Pattern

ARC-{PROJECT_ID}-{TYPE}-v{VERSION}.md

Examples:

ARC-000-PRIN-v1.0.md - Global principles (project 000)
ARC-001-REQ-v1.0.md - Requirements for project 001
ARC-002-DATA-v2.1.md - Data model for project 002, version 2.1

Multi-Instance Documents

Some commands generate multiple documents (Wardley Maps, Diagrams, ADRs):

ARC-{PROJECT_ID}-{TYPE}-{NUM}-v{VERSION}.md

Examples:

ARC-001-WARD-001-v1.0.md - First Wardley Map for project 001
ARC-001-DIAG-003-v1.0.md - Third diagram for project 001
decisions/ADR-001.md - First Architecture Decision Record

Document Type Codes

Code	Document Type	Command
PLAN	Project Plan	`/arckit.plan`
PRIN	Architecture Principles	`/arckit.principles`
STKE	Stakeholder Analysis	`/arckit.stakeholders`
RISK	Risk Register	`/arckit.risk`
SOBC	Strategic Outline Business Case	`/arckit.sobc`
REQ	Requirements	`/arckit.requirements`
PLAT	Platform Strategy	`/arckit.platform-design`
DATA	Data Model	`/arckit.data-model`
DPIA	Data Protection Impact Assessment	`/arckit.dpia`
DSCOUT	Data Source Discovery	`/arckit.datascout`
RSCH	Technology Research	`/arckit.research`
WARD	Wardley Map	`/arckit.wardley`
ROAD	Strategic Roadmap	`/arckit.roadmap`
STRAT	Architecture Strategy	`/arckit.strategy`
SOW	Statement of Work	`/arckit.sow`
DOS	Digital Outcomes & Specialists	`/arckit.dos`
GCLD	G-Cloud Service Search	`/arckit.gcloud-search`
GCFY	G-Cloud Clarification	`/arckit.gcloud-clarify`
EVAL	Vendor Evaluation	`/arckit.evaluate`
HLDR	High-Level Design Review	`/arckit.hld-review`
DLDR	Detailed Design Review	`/arckit.dld-review`
DIAG	Architecture Diagram	`/arckit.diagram`
BKLG	Product Backlog	`/arckit.backlog`
SNOW	ServiceNow Design	`/arckit.servicenow`
DVOP	DevOps Strategy	`/arckit.devops`
MLOP	MLOps Strategy	`/arckit.mlops`
FNOP	FinOps Strategy	`/arckit.finops`
OPS	Operational Readiness	`/arckit.operationalize`
TRAC	Traceability Matrix	`/arckit.traceability`
ANLZ	Governance Analysis	`/arckit.analyze`
PCOM	Principles Compliance	`/arckit.principles-compliance`
CONF	Conformance Assessment	`/arckit.conformance`
SVCA	Service Assessment	`/arckit.service-assessment`
TCOP	Technology Code of Practice	`/arckit.tcop`
SCUR	Secure by Design	`/arckit.secure`
AIPB	AI Playbook	`/arckit.ai-playbook`
ATRS	ATRS Record	`/arckit.atrs`
STORY	Project Story	`/arckit.story`
PRES	Presentation	`/arckit.presentation`

External Documents

ArcKit can read external documents (PDFs, images, Word docs) from external/ directories:

Project-Level External

projects/{project-id}/external/Place project-specific external documents here:

Vendor proposals (PDFs)
Existing architecture diagrams (PNG, SVG)
Compliance reports (Word, PDF)
Network topology (Visio, images)

Global External

projects/000-global/external/Place organization-wide external documents here:

Enterprise architecture standards
Security policies
Compliance frameworks
Portfolio roadmaps

Commands that read external documents:

/arckit.plan - Reads existing timelines, Gantt charts, dependency maps
/arckit.principles - Reads enterprise standards, security policies
/arckit.requirements - Reads existing requirements documents
/arckit.hld-review / /arckit.dld-review - Reads vendor design documents

Version Control

ArcKit is designed for git-based workflows:

What to Commit

Always commit:

projects/ - All architecture artifacts
.arckit/templates-custom/ - Your custom templates
.codex/prompts/ or .opencode/commands/ - Commands (for team sharing)
README.md, DEPENDENCY-MATRIX.md, WORKFLOW-DIAGRAMS.md

Never commit:

.codex/ (except prompts/ and README.md) - Contains auth tokens
.opencode/ (except commands/, agents/, skills/, opencode.json, README.md)
.envrc.local - Local direnv overrides

.gitignore

ArcKit creates a .gitignore automatically:

# Codex CLI - exclude auth tokens but include prompts
.codex/*
!.codex/prompts/
!.codex/README.md
!.codex/.gitignore

# OpenCode CLI - exclude auth but include commands
.opencode/*
!.opencode/commands/
!.opencode/agents/
!.opencode/skills/
!.opencode/opencode.json
!.opencode/README.md
!.opencode/.gitignore

# direnv
.envrc.local

Updating Your Project

When a new ArcKit version is released:

# Step 1: Upgrade the CLI tool
pip install --upgrade git+https://github.com/tractorjuice/arc-kit.git

# Step 2: Update your existing project
cd /path/to/your-existing-project
arckit init --here --ai codex  # or --ai opencode

This updates:

✅ .arckit/templates/ - Default templates
✅ .arckit/scripts/ - Automation scripts
✅ .codex/prompts/ or .opencode/commands/ - Command definitions
✅ VERSION, CHANGELOG.md - Version tracking

This preserves:

✅ projects/ - Your architecture artifacts
✅ .arckit/templates-custom/ - Your custom templates

Next Steps

Workflow

Understand the 16-phase ArcKit workflow

Templates

Learn how to customize ArcKit templates

AI Assistants

Choose your AI assistant platform

Get Started

Initialize your first ArcKit project

Get Started

Core Concepts

Governance Workflow

Vendor Procurement

Design & Review

UK Government Compliance

Guides

Project Structure

Project Structure

Directory Tree

Key Directories

`.arckit/`

`projects/`

`.codex/` or `.opencode/`

Filename Conventions

Document ID Pattern

Multi-Instance Documents

Document Type Codes

External Documents

Project-Level External

Global External

Version Control

What to Commit

.gitignore

Updating Your Project

Next Steps

Workflow

Templates

AI Assistants

Get Started

Build docs developers (and LLMs) love

Get Started

Core Concepts

Governance Workflow

Vendor Procurement

Design & Review

UK Government Compliance

Guides

​Project Structure

​Directory Tree

​Key Directories

​.arckit/

​projects/

​.codex/ or .opencode/

​Filename Conventions

​Document ID Pattern

​Multi-Instance Documents

​Document Type Codes

​External Documents

Project-Level External

Global External

​Version Control

​What to Commit

​.gitignore

​Updating Your Project

​Next Steps

Workflow

Templates

AI Assistants

Get Started

Build docs developers (and LLMs) love

Project Structure

Directory Tree

Key Directories

`.arckit/`

`projects/`

`.codex/` or `.opencode/`

Filename Conventions

Document ID Pattern

Multi-Instance Documents

Document Type Codes

External Documents

Version Control

What to Commit

.gitignore

Updating Your Project

Next Steps