Arkan Team Playbook

1. Introduction – Quick Action Version

1.1 Purpose

This Playbook is your daily guide, not a theory book. It tells you how we work, talk, and code at Arkan — one clear standard for everyone. It’s built from what we’ve learned, fixed, and improved together.

1.2 Scope

Applies to everyone in the team — backend, frontend, DevOps, documentation, or management. We follow four main pillars:

• Engineering Culture – how we think and plan.
• Code Culture – how we write and review code.
• Azure & DevOps – how we build and deploy.
• Communication & Collaboration – how we connect and support each other.

1.3 How to Use

• Read once, refer often.
• Check here first before asking — most answers are already written.
• Suggest improvements — if something’s missing, share it. The playbook grows with the team.

1.4 Ownership

• Reviewers: Mohamed Saeed + DevOps Lead
• Current Version: v1.0 – October 2025
• Every update must include version number, date, and author.

1.5 Why It Matters

• Faster onboarding for new members.
• Fewer mistakes and repeated questions.
• Clear, consistent way of working.
• A respectful, collaborative, and accountable team culture.

2. Engineering Culture – Quick Action Version

2.1 Purpose

Engineering at Arkan is about building systems that last, not just shipping features. We share one mindset: write clean code, solve problems early, and communicate clearly.

2.2 Core Principles

1. Keep It Simple
   • Write code anyone can read and maintain.
   • Avoid clever shortcuts that confuse others.
   • If it takes more than 5 minutes to explain, it’s too complex.
2. Be Consistent
   • Follow the existing naming, structure, and style.
   • Don’t reinvent the pattern — match the system.
3. Quality Is Everyone’s Job
   • Test before you say “done.”
   • Don’t close a PR until it’s reviewed and verified.
   • Bugs are shared problems — fix them, don’t blame.
4. Be Transparent
   • Speak up early about blockers.
   • Update your tasks on DevOps daily.
   • Share both wins and mistakes — both help the team grow.
5. Own Your Work
   • If you built it, you maintain it.
   • Don’t push code you wouldn’t use in production.
   • Take responsibility — not excuses.

2.3 Communication & Team Behavior

1. Be Clear. Use simple English. Say what’s done, not “it’s done.” Example: “File upload API tested — works for valid/invalid data on staging.”
2. Give Context Before You Ask. When you need help, include:
   • What you tried
   • What failed
   • Screenshot or error
   • Your guess why
3. Give Feedback Respectfully.
   • Talk about the code, not the person.
   • Appreciate publicly, correct privately.
   • Example: “This logic might break if null appears.”
4. Accept Feedback Maturely.
   • Listen first, respond later.
   • Don’t say “But it works on my machine.”
   • Say: “Got it, I’ll check and fix.”
5. Meetings
   • Be on time.
   • Prepare — know your updates.
   • End with clear next steps.
   • Write decisions in Teams or DevOps — never lose info in chat.
6. Respect Focus Time.
   • Don’t call unless urgent.
   • If not critical, leave a message or comment.
   • Everyone deserves quiet work time.
7. Cultural Awareness.
   • We’re an international team — be patient and respectful.
   • Avoid sarcasm or jokes that may not translate well.
   • If something’s unclear, ask — never assume.

2.4 Roles & Mindset

2.5 Daily Work Habits

• Be on time — commits, stand-ups, and meetings.
• Write notes — don’t trust your memory.
• Follow up after every meeting or task.
• Keep decisions documented.
• Help your teammates — no one wins alone.

2.6 Under Pressure

• Stay honest — don’t overpromise.
• Focus on priorities — not everything ships today.
• Fix stability before polish.
• Share the load — we succeed together.

2.7 Quick Reminder

Good engineers fix problems. Great engineers prevent them. Strong teams talk less, understand more.

3. Code Culture – Quick Action Version

3.1 Purpose

Code is communication — write it so others can read, use, and maintain it. We don’t just “make it work”; we make it clear, consistent, and long-lasting.

3.2 Core Rules

• Keep it simple. Short, readable, and direct code is better than “clever” code. If you can’t explain it in 5 seconds, rewrite it.
• One job per function. Each function should do one thing only. Split long or mixed logic immediately.
• Clean structure. Every file, folder, and variable should have a clear purpose. Group related logic — don’t mix concerns.
• Comment “why,” not “what.” Explain reasoning, not syntax. If the comment explains what the line does — fix the line instead.
• Quality is shared. Test before commit. Review with respect. Don’t push unreviewed or untested code.

3.3 Naming & Structure

a) General Naming Rules

b) Folder Structure Standards

Backend (.NET / C#) → Use PascalCase

Reason: Matches C# conventions for Classes and Namespaces.

/Modules/Documents
 ├── Controllers/
 ├── Services/
 ├── Repositories/
 ├── Models/
 ├── DTOs/
 └── Interfaces/
      

Frontend (Angular / TypeScript) → Use kebab-case

Reason: Matches Angular CLI default naming and import paths.

/src/app/modules/documents
 ├── components/
 ├── services/
 ├── models/
 └── pages/
      

Quick Note:

• Backend = PascalCase → Consistent with .NET standards.
• Frontend = kebab-case → Consistent with Angular structure and readability.
• Always follow the native convention of the stack you’re working on.

3.4 Commits

One purpose per commit.

Format → <type>: <short message>

Types: feat (new feature), fix (bug), refactor (cleanup), test (tests), chore (configs)

Examples:

• feat: add file versioning system
• fix: handle null project ID in FileService

3.5 Pull Requests (PRs)

• Keep PRs small and focused.
• Use clear summary, change list, and test steps.
• Don’t merge your own PR.
• Be kind in comments — suggest, don’t blame.

3.6 Review Checklist

• ✅ Follows naming rules
• ✅ No unused imports or console logs
• ✅ Tested before merge
• ✅ Validation and error handling included
• ✅ No secrets in code
• ✅ Docs updated if needed

3.7 Error Handling & Logging

• Catch and log all exceptions.
• Example: logger.LogError(ex, "File upload failed {FileId}", fileId)
• Never show stack traces or internal messages to frontend.
• Always return standard API responses.

3.8 Security Practices

• Never hardcode tokens or passwords.
• Use environment variables or Azure Secrets.
• Validate all inputs.
• Encrypt sensitive data when stored.
• Log user actions for traceability.

3.9 Quick Tips

• Write less, think more — fewer lines = fewer bugs.
• Commit daily, not weekly.
• Review with empathy — help, don’t judge.
• Read your code out loud — if it sounds messy, fix it.
• End every task with cleanup — remove logs and unused imports.

3.10 Remember

“Clean code is not just written — it’s maintained.” “Clarity beats cleverness every time.”

4. Azure & DevOps Essentials – Quick Action Version

4.1 Goal

One process for all repos — same branches, same pipelines, same rules. DevOps is not a step; it’s how we build.

4.2 Repo Setup

4.3 Branching Model (Main-based with Personal Namespaces)

• main → production only (protected, PR + approval + checks)
• test → integration/staging (protected, PR + checks)
• <initials>/feature/<name> → new feature work
• <initials>/hotfix/<name> → urgent fix
• <initials>/release/<version> → optional pre-prod hardening
• Developers never push to main or test directly.

4.4 Developer Initials

4.5 Branch Flow

1. Create from latest test: <initials>/feature/<short-name>.
2. Push daily → CI runs (build, lint, unit tests).
3. Open PR to test → code review → merge.
4. test auto-deploys to Staging.
5. When stable: PR test → main (manual approval) → Production deploy.

4.6 Naming Rules

• Lowercase + hyphen: is/feature/file-versioning
• Types: feature, hotfix, release, spike, poc
• Short, meaningful names: hm/feature/drawings-smart-pins

4.7 Branch Lifetime

4.8 Pipelines

4.9 Environments

4.10 Branch Policies (Azure Repos)

• main: Block direct pushes; PR required; 1+ reviewer; successful build; linked Work Item.
• test: PR required; successful build; optional 1 reviewer.
• Auto-complete only when checks pass; delete source branch on merge.

4.11 Secrets & Config

• Never commit keys or tokens.
• Use Azure Key Vault / DevOps Library → env vars.
• Example: AzureBlob__ConnectionString = $(AzureBlobConnectionString)

4.12 Monitoring

• Application Insights on all apps.
• Alerts via Action Group: ArkanOpsTeam.
• Each deploy stamps build version in telemetry.

4.13 Final Rules

• Developers push to personal branches only.
• PR → test (staging), then PR → main (production).
• Small PRs, fast reviews, and weekly cleanup for stale branches.

5. Communication & Collaboration – Quick Action Version

5.1 Purpose

We keep things clear, respectful, and written. Good communication prevents wasted hours, missed details, and wrong assumptions.

5.2 Core Rules

1. Be Clear. Use simple words, short sentences. If your message can be misunderstood, rewrite it. Don’t say “It’s done.” → Say what is done and where.
2. Give Context. Always include screenshots, URLs, version numbers, or logs. Example: “Upload failed on staging (ArkanCore v1.2.3) for files >20 MB — see console log.”
3. Stay Respectful. Critique work, not people. Praise publicly, correct privately.
4. One Source of Truth. Tasks, reviews, and decisions belong in Azure DevOps. Teams / WhatsApp are for quick coordination only.

5.3 Communication Channels

5.4 Meetings

• Start with a goal, end with clear next steps.
• Be on time; avoid side chats.
• End when done, not when the clock ends.
• Always write a short summary after the call (Teams note or DevOps Wiki). If there’s no written outcome, it didn’t happen.

5.5 Feedback

Giving:

• Focus on code, not the person.
• Start with what worked, then what to fix.
• Example: “Good structure — let’s add validation at controller level.”

Receiving:

• Listen first, don’t defend.
• Assume good intent.
• Reply with “Got it” or “Thanks, I’ll check it.”

5.6 Response Time

No silent delays — silence kills flow.

5.7 Conflict Handling

• Recheck the facts (code / task / goal).
• Discuss privately first.
• If still stuck, escalate respectfully to the Project Owner.
• End with a decision, not emotion. Conflict = feedback, not failure.

5.8 Collaboration Habits

• Write everything down. Update Wiki or task after any decision.
• Stay visible. Update your task board daily (To Do / In Progress / Done).
• Support each other. If someone’s blocked, help. Share tools, notes, and fixes.

5.9 Daily Reminder

“Clear communication turns good teams into great ones.” Say less — mean more. Document everything.

6. Knowledge Sharing – Quick Action Version

6.1 Purpose

In Arkan, knowledge is shared, not owned. Everyone learns, teaches, and documents — so the team keeps improving, even when people change.

6.2 Core Mindset

• No silos. Anything useful you learn → write it down. If someone asks you twice → document it.
• Learn every week. Add one skill, tool, or shortcut each week. Learning is part of work, not a break from it.
• Teach what you learn. Share in DevOps Wiki or the #learning channel. Teaching = the fastest way to master it.

6.3 Weekly Knowledge Rhythm

Keep them short. Always record key points in Teams or Wiki.

6.4 Documentation Habits

• Every new feature or API must include: Purpose / Inputs / Outputs / Author / Update date.
• Store docs in /docs folder or ArkanDocs repo.
• Treat docs like code — version, review, and update.
• Outdated docs = silent bugs.

Example:

/docs/performance-tips.md

"Caching static assets in Azure FrontDoor improved load time by 40%."
      

6.5 Mentoring & Peer Learning

• Mentoring = helping, not hierarchy.
• Seniors guide logic, naming, and architecture.
• Juniors share new tools or trends.
• Use pair programming or shadowing for onboarding.

6.6 Internal Knowledge Map

If you can’t find something → ask, then document it for the next person.

6.7 Curiosity Rules

• Ask questions — it shows initiative, not weakness.
• If you’re confused, someone else probably is too.
• Share improvements, no matter how small.
• Don’t wait for permission to share — learning is open-source.

6.8 Reminder

“A great team doesn’t keep knowledge — it spreads it.” “When we share what we know, everyone levels up.”

7. Appendix & Glossary – Quick Action Version

7.1 Quick Templates

Pull Request (standard)

### Summary
What this PR does and why.

### Changes
- Added <feature>
- Fixed <issue>
- Updated <logic>

### Testing
1. Steps to verify
2. Expected result

### Linked Work Item
#<ID>
      

Email Update

Subject: [Action Required] – <Task/Feature>

Hi <Name>,

Quick update:
- Status: <done / pending / blocked>
- Next step: <who + what>
- ETA: <date>

Best,
<Your Name> – Arkan Team
      

Meeting Summary

Date: <dd Mon yyyy>
Attendees: <names>
Goal: <topic>

Key Points:
- <decision 1>
- <decision 2>

Action Items:
- [Name] <task> by <date>
      

Work Item Naming

Docs (Markdown Template)

# Feature: <Name>
Author: <Name> | Updated: <Date>

## Overview
Brief description.

## Flow
1. Step 1
2. Step 2

## API
POST /api/...
GET /api/...

## Notes
Extra info or dependencies.
      

7.2 Glossary – Core Terms

7.3 Arkan Repositories Quick Map

7.4 Key Contacts

7.5 Final Note

Tools change — culture doesn’t. The best thing we build at Arkan is how we work together.