Team Repository — Architecture Overview

Client

Browser React Server Components RSC React Client Components 'use client'

↕

Frontend

Next.js 14.2 App Router TypeScript 5 Tailwind CSS 3.4 shadcn/ui Radix UI lucide-react js-yaml mermaid 11 marked react-markdown + remark-gfm

↕

API

Next.js Route Handlers middleware.ts password gate + CSRF Rate limit in-memory 5/min/IP

↕

Data

octokit 5 GitHub REST + git trees arch-data repo jazzwedz/arch-data YAML per component /components/{id}.yaml Drawio diagrams /diagrams/{name}.drawio Confluence link side-files /confluence-links/{id}.json No DB — Git as storage

↕

AI

@anthropic-ai/sdk 0.80 Claude Sonnet 4 claude-sonnet-4-20250514 Use cases Generate · Blast Radius memo · Pull-smart scan

↕

External

Atlassian Cloud Confluence REST v2 Draw.io mxlibrary XML export

↕

Infra

Railway arch-tool service GitHub jazzwedz/arch-tool Env vars see Deployment

🖥 Pages App Router

GET

/login

Password gate

GET

/

Catalog (cards / tiles / list)

GET

/component/[id]

Detail — 7 tabs

GET

/edit/[id]

Edit component form

GET

/new

Create component

GET

/diagrams

Diagram list + preview

GET

/diagrams/builder

WYSIWYG drawio builder

GET

/generate

Diagram-level doc gen

GET

/export

Drawio library guide

GET

/architecture.html

This page

⚡ API Route Handlers

POST

/api/auth/login

Password → cookie

GET

/api/components

List all

POST

/api/components

Create

GET

/api/components/[id]

Read

PUT

/api/components/[id]

Update

DELETE

/api/components/[id]

Delete

GET

/api/components/[id]/history

Git commit log

GET

/api/components/[id]/diagrams

Refs from diagrams

GET

/api/components/[id]/blast-radius

Reverse-graph BFS

POST

/api/components/[id]/blast-radius/memo

AI Impact Memo

POST

/api/generate

AI doc (audience / doctype)

POST

/api/confluence/publish

Render + publish page

POST

/api/confluence/pull-smart

AI scan → patches

GET

/api/confluence/status

Per-component sync state

GET

/api/diagrams · /[name] · /preview

CRUD + render

GET

/api/export/drawio

mxlibrary XML

🐙 GitHub (arch-data)

repo: jazzwedz/arch-data
branch: main
auth: GITHUB_TOKEN (PAT)
format: YAML per file
structure: components/ · diagrams/ · confluence-links/

🤖 Anthropic Claude

model: claude-sonnet-4-20250514
SDK: @anthropic-ai/sdk 0.80
auth: ANTHROPIC_API_KEY
3 use cases (docs · memo · pull scan)

📘 Confluence Cloud

base: jasenovec.atlassian.net
space: TR (Team Repository)
API: REST v2
auth: Basic (email + API token)
publish + pull bidirectional

📐 Draw.io Export

format: mxlibrary XML
16 component types pre-styled
8 connector templates
drag-and-drop palette

🚂 Railway

service: arch-tool
repo: jazzwedz/arch-tool · main
url: arch-tool-jaso.up.railway.app
auto-deploy on push to main

GET

POST

PUT

DELETE

🔷 Core fields

id: string // kebab-case

name: string

type: ComponentType

16 types: microservice · frontend · database · queue · gateway · external · platform · library · data-pipeline · storage · batch-job · cache · context · boundary · application · module

status: ComponentStatus // draft · production · deprecated

owner: string

tags: string[]

description: { oneliner · technical · business }

interfaces: ComponentInterface[]

direction (provides | consumes) · type · target

relationships: ComponentRelationship[]

7 types: parent-of · child-of · depends-on · communicates-with · reads-from · writes-to · fallback

risks: string[] ?

nfr: ComponentNFR ?

availability · rto · rpo · max_latency · throughput · data_classification · scaling

diagram: ComponentDiagram ? // color · shape

🌿 Rich modelling fields

capabilities: ComponentCapability[] ?

{ name · role · description? }

role: owner · contributor · consumer · indirect

data: ComponentData ? // inputs[] · outputs[] · owns[]

DataItem: name · kind · source? · consumers? · purpose? · description?

Format: table · file · stream · message · form

Business: event · command · document · decision · signal

Technical: business · reference · cache · config · transient · logs

processes: ComponentProcess[] ?

{ name · role · activity? · description? }

role: owner · participant · listener · trigger

rules: ComponentRule[] ? // business logic

kind: formula (expression) · rule (Given/When/Then) · constraint (invariant + enforced_in)

Storage: each component is one {id}.yaml file. Git history = audit log. Backward-compat: legacy business_capabilities: string[] auto-migrates to capabilities: [{name, role: indirect}] on read; legacy data.consumes / produces → data.inputs / outputs.

📊

Above every tab: Identity panel (type · status · owner · tags) + Documentation maturity % (13 fields scored, banded Skeletal / Drafted / Solid / Complete).

Overview All

Hero Component Context diagram (mermaid: inputs · outputs · owned data · relationships in one), Details, Descriptions, Risks.

Technical Dev

Interfaces (with Visualize toggle), Relationships (with Visualize toggle), Non-Functional Requirements.

Business BA

Capabilities (table with role badges, Visualize toggle), Inputs & Outputs (3 sub-tables, Visualize toggle), Processes.

Rules & Calculations BA

Formula cards (monospace), Behavioural rules (Given/When/Then), Constraints (red, with enforced_in component links).

Blast Radius Ops

Reverse-graph BFS over relationships. Severity HIGH (depends-on, child-of, reads-from, writes-to) / MEDIUM (others). Stat cards + mermaid graph + layered impact list + AI Impact Memo.

Documentation All

Generate (audience or doctype), Confluence (Publish + Open + Pull), Export (Draw.io library, Copy ID / Tech / Business descriptions).

Diagrams All

List of diagrams in /diagrams that reference this component (matched by arch_id attribute). Click → open preview modal.

History Ops

Git commit log for the component's YAML file — who, when, what message. Last 50 commits.

⚡

AI Documentation Generator

Claude Sonnet 4 · 3 audiences · 3 doctypes · attachments

Component or diagram → audience (Technical / Business / Executive) or doctype (Detailed Solution / Audit Report / Security Report). Output is markdown with mermaid blocks rendered client-side. Optional attachments: PDF business req, ERD, BPMN — enrich the prompt.

💥

Blast Radius Analysis

Reverse-graph BFS · NFR gap detection · AI Impact Memo

Click component → walk reverse-relationship graph (max depth 3). Direct + transitive impactors, severity per relationship type, NFR gaps (production without RTO), confidential-data flags. Mermaid graph + layered list. One-click "Generate AI Impact Memo" → 1-page exec-style brief.

📤

Confluence Publish

Storage XHTML · tables + panels · TOC macro

Renders structured Component Reference (At a glance · Capabilities · Interfaces · Relationships · I/O · Processes · Rules · NFR · Risks) as native Confluence tables. Rules use info / tip / warning panel macros. AI narrative above. Mermaid blocks stripped (no plugin). Hierarchy mirrors first capability.

🔄

Confluence Pull-smart

Claude scan · scalar + indexed rule patches · diff dialog

AI compares Confluence page text to catalog YAML, proposes field-level patches (scalar fields + indexed rules[N].field paths). Each patch has confidence + evidence quote. User ticks per-patch, "Apply & commit" pushes to arch-data. Bidirectional sync without leaving arch-tool.

📐

WYSIWYG Diagram Builder

drawio palette · 8 connector types · save to repo

Drag pre-styled components (matching catalog types) onto canvas, click-to-connect with 8 typed connectors (rest · grpc · async · db · file · human · info · link). Save .drawio XML to diagrams/ in arch-data. Each diagram is preview-able as mermaid (drawio → mermaid conversion).

📊

Hero Context Diagram

Per-component mermaid · auto-rendered · 5 dimensions

On every component's Overview tab, an auto-rendered mermaid flowchart combines inputs (left, green) · outputs (right, pink) · owned data (bottom, purple cylinders) · relationships (top, gray dotted). The picture you see first.

📤 Publish flow

Generate AI markdown (or reuse existing draft)
Strip mermaid blocks (no plugin in target Confluence)
marked → HTML → Confluence storage format
Replace manual TOC with native toc macro
Append "Component Reference" — auto tables + rule panels
Find-or-create capability parent page (page-tree hierarchy)
Find existing page (side-file → title fallback) → update; else create
Persist side-file confluence-links/{id}.json (best-effort)

⇄

📥 Pull-smart flow

Resolve page id (side-file → title-based fallback)
Fetch page storage body
Convert storage XHTML to plain text (strip macros)
Send to Claude with current YAML + editable schema (scalar + rules[N].*)
Claude returns JSON: per-field patches with confidence + evidence
UI: checkbox dialog (low-confidence unticked by default)
Apply selected → validate enums → save YAML → commit to git

Patch protocol limits today: scalar fields (name · status · owner · tags · description.* · nfr.*) and indexed rule fields (rules[N].name · kind · summary · description · formula · given · when · then · enforced_in). Out of scope: add/remove rules in Confluence; capabilities · data · processes · interfaces · relationships round-trip — edit those in arch-tool's editor.

GitHub (storage)

GITHUB_TOKEN=ghp_… // fine-grained PAT, Contents R/W on arch-data
GITHUB_OWNER=jazzwedz
GITHUB_REPO=arch-data
GITHUB_BRANCH=main

Anthropic Claude

ANTHROPIC_API_KEY=sk-ant-…
// model hardcoded: claude-sonnet-4-20250514

Confluence Cloud

CONFLUENCE_BASE_URL=https://jasenovec.atlassian.net
CONFLUENCE_EMAIL=jasenovec@gmail.com
CONFLUENCE_API_TOKEN=ATATT…
CONFLUENCE_SPACE_ID=229575
CONFLUENCE_SPACE_KEY=TR

App self-reference

ARCH_TOOL_PUBLIC_URL=https://arch-tool-jaso.up.railway.app
SITE_PASSWORD=… // password gate (middleware.ts)

Deploy: push to main → Railway auto-builds Next.js → serves on internal port (8080). Public URL via Railway-managed TLS. Single replica (in-memory rate limiter not yet Redis-backed). Watch-branch main; if pushing to master, also push to main for the build to fire.

Goal

Move the running app from Railway + GitHub.com + Anthropic.com + Atlassian Cloud into a regulated corporate environment where storage, LLM access, and auth go through internal endpoints. Code path is largely adapter-swap; the costly part is corporate process (provisioning, security review, sign-offs).

Total estimate: ~3.5–5 person-days assuming prerequisites are done and no corp blocker surfaces. Standalone migration plan + architecture-questions checklist live in Downloads/team-repo-port-*.md.

Six phases

A — Foundation

Refactor external calls behind interfaces: LLMClient · StorageClient · ConfluenceClient · AuthMiddleware. ~0.5 MD

B — Storage adapter

Implement StorageClient against corp Git provider; bootstrap empty arch-data repo. ~0.5–1 MD

C — LLM gateway

Route all AI calls through corp gateway; re-tune prompts if model isn't Claude-class. ~1 MD

D — Auth & ingress

Swap password gate for SSO (ingress-based header read or SDK). ~0.5 MD

E — Deploy

Containerise, corp secrets / registry / manifests, smoke test in dev + test envs. ~0.5–1 MD

F — Handover

User / admin / runbook docs, prod promote, sign-offs from security · IT ops · line manager. ~0.5 MD

Prerequisites (before Phase A): signed ADR with architecture decisions · senior-dev pairing scheduled · corp infra tickets open (Git repo · K8s namespace · SSO group · secret store) · naming convention + default capability list + team identifiers agreed. Architecture-questions checklist exposes ~110 items to triage — half are typically relevant.