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

Tue, 03 Feb 2026 00:00:00 +0000

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:

Gathering context (business, technical, operational)
Assessing maturity (architecture, code, processes)
Aligning expectations (with PM, Tech Lead, team)
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:

Request intro from PM:
- What’s the project?
- What problems does it solve?
- Who’s the Tech Lead?
Request access:
- Repositories (GitHub/GitLab)
- Monitoring (Grafana/Prometheus)
- Documentation (Confluence/Notion)
- CI/CD (Jenkins/GitLab CI)
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:

Business context (10 min)
- Why this project?
- Who are the users?
- What are success metrics?
Technical picture (30 min)
- Architecture (components, integrations)
- Stack (languages, frameworks)
- Operations (deployment, monitoring, incidents)
Oversight expectations (20 min)
- What’s needed from architect?
- How often syncs?
- Code review/Design review?
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:

Checklist (11 sections, 80+ items)
Report template (12 sections)
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:

Report presentation (30 min)
Critical issues discussion (20 min)
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:

Join communications:
- Slack/Teams channels
- Standups
- Retros
Set up regular touchpoints:
- Weekly sync with Tech Lead (30 min)
- Design review (on demand)
- ADR review (as created)
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:

Onboarding process (6 phases)
- Each phase description
- Time frames
- Communication templates
Onboarding checklist (11 sections, 80+ items)
- Business context
- System analysis
- Architecture
- Code and tests
- CI/CD
- Monitoring
- …
Audit template (12 sections)
- Report structure
- Evaluation criteria
- Recommendations format
Automated validation (215 metrics)
- Checklist verification
- Scoring (1-10)
- Automatic report

Where to look:

Onboarding process: github.com/mshogin/archlint/templates/project-handover
System audit: github.com/mshogin/archlint/templates/system-audit

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:

Week 1: Initiation + kickoff for all 4 projects
Weeks 2-3: Information gathering and audit (parallel)
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:

Test on 4 projects
Gather feedback
Improve process
Write second article with real experience

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

Processes on Mikhail Shogin