Architecture

How to Onboard 4 Projects into Architectural Oversight Without Losing Your Mind

The Problem

Four projects simultaneously. Different teams, different stacks, unclear functional overlaps. “Figure it out” - the only instruction.

Classic situation: manager delegates, architect takes responsibility, but how to onboard projects systematically - unclear.

Questions:

  • Where to start?
  • What to check first?
  • How not to miss critical issues?
  • How many days will it take?

Keeping everything in your head is pointless. Need a process.

Symptoms of Chaos

When there’s no onboarding process, chaos begins.

Symptom 1: Archaeological Excavation

Architect spends a week searching for documentation. Slack, Confluence, Google Drive, wiki - information scattered everywhere. Half is outdated from a year ago. Half needs to be reconstructed from code.

Result: 5 days wasted.

Symptom 2: Unexpected Problems

A month after onboarding: monitoring doesn’t exist, tests don’t cover critical paths, CI/CD runs on workarounds. Too late to fix - project already in production.

Result: Firefighting instead of oversight.

Symptom 3: Team Conflicts

Architect starts changing code without context. Tech Lead resists: “We’ve been doing it this way for a year, why change?”

Result: Loss of trust.

Diagnosis: Need a System

Problem isn’t in projects. Problem is lack of process.

Project onboarding isn’t about code. It’s about:

  1. Gathering context (business, technical, operational)
  2. Assessing maturity (architecture, code, processes)
  3. Aligning expectations (with PM, Tech Lead, team)
  4. Improvement plan (prioritization and timeline)

Without a formal process, you reinvent the wheel every time.

Solution: 6-Phase Process

Studied industry practices (Futurice, TOGAF, Harvard EA) and assembled an onboarding process.

Process Phases

1
2

[Initiation] -> [Kickoff] -> [Info Gathering] -> [Audit] -> [Plan Agreement] -> [Onboarding]
   1 day        1-2 hours      3-5 days         3-7 days     1 day           ongoing

Total time: 7-14 days.

Phase 1: Initiation (1 day)

Goal: Get basic information and access.

Actions:

  1. Request intro from PM:

    • What’s the project?
    • What problems does it solve?
    • Who’s the Tech Lead?

  2. Request access:

    • Repositories (GitHub/GitLab)
    • Monitoring (Grafana/Prometheus)
    • Documentation (Confluence/Notion)
    • CI/CD (Jenkins/GitLab CI)

  3. Schedule kickoff meeting.

Result: Basic project understanding, all access granted.

Phase 2: Kickoff (1-2 hours)

Goal: Sync with PM and Tech Lead.

Participants:

  • PM (business context)
  • Tech Lead (technical picture)
  • Architect (onboarding)

Agenda:

  1. Business context (10 min)

    • Why this project?
    • Who are the users?
    • What are success metrics?

  2. Technical picture (30 min)

    • Architecture (components, integrations)
    • Stack (languages, frameworks)
    • Operations (deployment, monitoring, incidents)

  3. Oversight expectations (20 min)

    • What’s needed from architect?
    • How often syncs?
    • Code review/Design review?

  4. Next steps (10 min)

    • Documentation gathering
    • Audit dates
    • Report format

Result: Everyone aligned, plan agreed.

Phase 3: Information Gathering (3-5 days)

Goal: Collect everything needed for audit.

What we gather:

1. Documentation

  • Architecture (C4, ADR)
  • API specs (OpenAPI/Swagger)
  • Business processes (BPMN)
  • Incidents (postmortems)

2. Code

  • Repo structure
  • Test coverage
  • Code quality (linters, code review)

3. Infrastructure

  • CI/CD pipeline
  • Deployment (Kubernetes/Docker)
  • Monitoring (metrics, alerts)
  • Logs (structured, retention)

4. Operational

  • SLA (uptime, latency)
  • Incident history
  • Escalation processes

Result: Folder with materials for audit.

Gathering checklist:

1
2
3
4
5
6
7
8

- [ ] Architecture documentation (C4, ADR)
- [ ] API specifications (OpenAPI)
- [ ] Database schema (ER-diagram)
- [ ] CI/CD pipeline (configs)
- [ ] Monitoring (Grafana dashboards)
- [ ] Incident history (postmortems)
- [ ] Test coverage (coverage report)
- [ ] Team processes (code review, standup)

Phase 4: Audit (3-7 days)

Goal: Understand current project state.

Audit levels:

Level 1: Architecture Overview (1-2 days)

  • System structure (components, layers)
  • Bounded contexts (if microservices)
  • Integrations (sync/async)
  • Tech debt map

Level 2: Deep Dive (2-4 days)

  • Code (smells, complexity, duplicates)
  • Tests (coverage, quality, fragility)
  • CI/CD (speed, reliability, rollback)
  • Monitoring (completeness, alerting, observability)

Level 3: Operational (1 day)

  • SLA vs actual
  • Incidents (frequency, recovery time)
  • Team processes (code review, ADR, standups)

Audit tools:

I assembled an audit template together with Claude Code (~3882 lines of config). Read and edited it.

What resulted:

  1. Checklist (11 sections, 80+ items)
  2. Report template (12 sections)
  3. Automated validation (215 metrics)

Validation example:

1
2
3
4
5
6
7
8
9

# Test coverage check
$ archlint validate --template system-audit --project ./my-project

✓ Test coverage: 78% (target: >70%)
✗ Critical paths coverage: 45% (target: >80%)
✓ CI/CD pipeline: green
⚠ Monitoring: missing SLO alerts

Score: 7/10 (acceptable with improvements)

Audit result:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

# Audit Report for {ProjectName}

Date: YYYY-MM-DD
Architect: {Name}

## Executive Summary
- Status: Acceptable with improvements
- Critical issues: 3
- Needs attention: 12
- Score: 7/10

## Critical Issues (P0)
1. No SLO monitoring
2. Critical path coverage <50%
3. Missing ADR process

## Needs Attention (P1)
...

## Recommendations
...

Phase 5: Improvement Plan Agreement (1 day)

Goal: Agree on action plan with team.

Format: Meeting with PM and Tech Lead (1 hour).

Agenda:

  1. Report presentation (30 min)
  2. Critical issues discussion (20 min)
  3. Improvement plan (10 min)

Three plan types depending on state:

Plan 1: Stable Project

  • Non-critical issues
  • Quarterly improvement plan
  • Focus: development and optimization

Plan 2: Quick Fixes Needed

  • Critical issues present
  • Fix plan: 2-4 weeks (priority)
  • Then quarterly improvement plan

Plan 3: Stabilization Required

  • Multiple critical issues
  • Stabilization plan: 1-3 months
  • Oversight in firefighting mode
  • After stabilization - transition to development

Result: Agreed action plan with priorities and timelines.

Phase 6: Onboarding (ongoing)

Goal: Integrate into team.

Actions:

  1. Join communications:

    • Slack/Teams channels
    • Standups
    • Retros

  2. Set up regular touchpoints:

    • Weekly sync with Tech Lead (30 min)
    • Design review (on demand)
    • ADR review (as created)

  3. Define control points:

    • Code review of critical changes
    • ADR approval
    • Pre-release review

Result: Architect integrated into team.

Process Artifacts

Formalized the entire process as templates.

What I created:

  1. Onboarding process (6 phases)

    • Each phase description
    • Time frames
    • Communication templates

  2. Onboarding checklist (11 sections, 80+ items)

    • Business context
    • System analysis
    • Architecture
    • Code and tests
    • CI/CD
    • Monitoring
    • …

  3. Audit template (12 sections)

    • Report structure
    • Evaluation criteria
    • Recommendations format

  4. Automated validation (215 metrics)

    • Checklist verification
    • Scoring (1-10)
    • Automatic report

Where to look:

Success Metrics

How to know the process works?

Metric 1: Onboarding time

  • Target: < 2 weeks
  • Measure: from initiation to onboarding
  • Why important: quick oversight start

Metric 2: Critical issues closure

  • Target: > 80% per quarter
  • Measure: percent of closed P0 from report
  • Why important: real quality impact

Metric 3: Tech Lead satisfaction

  • Target: > 4/5
  • Measure: survey after 3 months oversight
  • Why important: team trust

Metric 4: Design review participation

  • Target: > 90%
  • Measure: percent of reviews architect participated in
  • Why important: process involvement

Usage Example

Theory so far. Next week I start onboarding 4 projects - let’s see what breaks in reality.

Plan:

  1. Week 1: Initiation + kickoff for all 4 projects
  2. Weeks 2-3: Information gathering and audit (parallel)
  3. Week 4: Decision + onboarding

Will track:

  • Where process got stuck
  • Which checklist items were useless
  • How long each phase took
  • What problems weren’t detected

After completion - will write second article with real experience and gotchas.

Summary

What’s done:

  • 6-phase onboarding process (7-14 days)
  • Checklist (11 sections, 80+ items)
  • Audit template (12 sections)
  • Automated validation (215 metrics)

Why it matters:

  • Systematic approach instead of chaos
  • Reproducible process
  • Control of critical aspects
  • Measurable success metrics

What’s next:

  1. Test on 4 projects
  2. Gather feedback
  3. Improve process
  4. Write second article with real experience

How do you onboard projects? And do you use AI for audits?

© 2025 - 2026 Михаил Шогин
Built with Hugo
Theme Stack designed by Jimmy