GitHub

Orcta Internal Docs

Welcome to the internal documentation hub for Orcta Technologies. These guides capture who we are, what we build, and how we deliver work so teams can move fast with shared context.

Start Here

  • Company - Mission, story, and values that guide decisions
  • Products - Current product portfolio and product overviews
  • Services - What we offer clients and how we deliver
  • Engineering - Workflow, standards, and review practices
  • Infrastructure - Deployment, VPS, and production runbooks
  • Insights - Philosophies, quotes, and short internal posts

How to Use These Docs

Each section is meant to be short, actionable, and updated as we evolve. If you spot gaps or outdated details, open a PR with the change and include a brief rationale.

Edit this page

Company

Core context about Orcta Technologies for internal alignment and external consistency.

Edit this page

Mission & Positioning

Orcta exists to bridge innovation and humanity. We transform complex challenges into reliable, well-designed products that serve real users and evolve with purpose.

Positioning statement: Orcta Technologies designs and engineers thoughtful digital and embedded systems that balance performance, reliability, and human experience.

Edit this page

Company Story

Orcta Technologies is a Ghana-based technology company focused on practical, sustainable solutions across software, hardware, electronics, and robotics. We started as a small team of thinkers and builders who believed technology should understand people, not the other way around.

Since 2019, our team has delivered innovative and scalable systems for clients worldwide. By combining software and embedded systems under one roof, we can build complete ecosystems where apps, devices, and users connect seamlessly.

Edit this page

Values & Principles

  • Empathy first: design and build for real people and real contexts.
  • Reliability by default: systems must be stable, predictable, and resilient.
  • Performance with purpose: optimize for outcomes that matter, not vanity metrics.
  • Design with intent: clear UX and thoughtful interactions are non-negotiable.
  • Trust at the core: we earn long-term partnerships through transparency and follow-through.
Edit this page

Products

Current product portfolio and internal product summaries.

Edit this page

KNUST Career App

A centralized digital platform designed to support KNUST students and alumni throughout their career journey, from skills development to job placement.

Core Capabilities

  • Personalized opportunities for jobs, internships, scholarships, and National Service.
  • Student profiles with academic background, skills, certifications, and goals.
  • Dashboard for career events, applications, and progress tracking.
  • Built-in chatbot for instant guidance and common questions.
  • Mentorship, resume building, and skill development tools to improve readiness.

Primary Users

  • Students and alumni seeking opportunities and career support.
  • Career services teams managing programs, events, and guidance.
Edit this page

Orcta Go

A smart mobility platform that simplifies daily transportation by enabling pre-booked shared rides and commercial buses with predictable pricing and schedules.

Core Capabilities

  • Seat reservations in advance for shared transport.
  • Clear visibility into pickup points, routes, and schedules.
  • Predictable and affordable pricing for commuters.
  • Reduced waiting times and overcrowding through structured routing.

Primary Users

  • Daily commuters seeking reliable, low-stress transport.
  • Transport operators coordinating routes and capacity.
Edit this page

Services

Service lines offered by Orcta Technologies and how we approach delivery.

Edit this page

Digital Product Development

We design and engineer custom software solutions that help teams move faster, work smarter, and build products people enjoy using.

What We Deliver

  • Web applications and platforms that scale with business growth.
  • Secure, efficient systems that simplify operations.
  • End-to-end delivery from discovery through deployment.
Edit this page

IoT & Embedded Systems

We bridge software and hardware to build complete ecosystems where devices, data, and users connect seamlessly.

What We Deliver

  • IoT integrations and device connectivity.
  • Embedded software for real-world environments.
  • Systems designed for reliability and long-term maintenance.
Edit this page

Applied AI

We build AI capabilities that support decisions, automate workflows, and integrate cleanly into existing products and operations.

What We Deliver

  • Automation and prediction features that reduce manual effort.
  • AI services designed for human-in-the-loop workflows.
  • Practical, measurable outcomes instead of novelty projects.
Edit this page

Design & UX

We design experiences that are intuitive, accessible, and built to scale as products grow.

What We Deliver

  • User-centered UI and UX design grounded in real workflows.
  • Prototypes and design systems that align teams quickly.
  • Interfaces that reinforce trust and usability across platforms.
Edit this page

Architecture Review

We assess technology stacks to uncover bottlenecks, risks, and opportunities to improve reliability and performance.

What We Deliver

  • System audits focused on scalability and resilience.
  • Recommendations for tooling, infrastructure, and code quality.
  • Clear next steps with prioritized improvements.
Edit this page

Engineering

Engineering Documentation

Everything you need to build, ship, and maintain great software at Orcta. From workflow guides to coding standards.

Start with the Workflow Open the Cheat Sheet

Quick Start Guides

Practical, actionable guides for daily development work.

Engineering Cheat Sheet

One-page reference with core beliefs, non-negotiables, and naming conventions.

1 page 5 min read 
  <a href="development-workflow/" class="doc-card">
    <h4 class="card-title">Development Workflow</h4>
    <p class="card-description">
      Complete workflow from idea to production. Design, build, test, review, deploy, and monitor.
    </p>
    <div class="card-meta">
      <span class="card-meta-item">8 steps</span>
      <span class="card-meta-item">15 min read</span>
    </div>
  </a>

  <a href="git-workflow/" class="doc-card">
    <h4 class="card-title">Git Workflow - using React</h4>
    <p class="card-description">
      Branching strategy, commit conventions, and PR process for React development with our template.
    </p>
    <div class="card-meta">
      <span class="card-meta-item">10 steps</span>
      <span class="card-meta-item">20 min read</span>
    </div>
  </a>

  <a href="pr-guidelines/" class="doc-card">
    <h4 class="card-title">PR Template &amp; Guidelines</h4>
    <p class="card-description">
      What to include in every pull request. Checklist for authors and guidelines for reviewers.
    </p>
    <div class="card-meta">
      <span class="card-meta-item">Template</span>
      <span class="card-meta-item">5 min read</span>
    </div>
  </a>

  <a href="onboarding/" class="doc-card">
    <h4 class="card-title">Onboarding Checklist</h4>
    <p class="card-description">
      A 90-day roadmap for new engineers. Week-by-week tasks from setup to ownership.
    </p>
    <div class="card-meta">
      <span class="card-meta-item">90 days</span>
      <span class="card-meta-item">10 min read</span>
    </div>
  </a>

  <a href="playbook-in-practice/" class="doc-card">
    <h4 class="card-title">Playbook in Practice</h4>
    <p class="card-description">
      Real stories from Orcta engineering. Learn from what went well and what did not.
    </p>
    <div class="card-meta">
      <span class="card-meta-item">6 stories</span>
      <span class="card-meta-item">15 min read</span>
    </div>
  </a>
</div>

Complete Documentation

In-depth resources covering all aspects of engineering at Orcta.

Engineering Philosophy

Our core beliefs about how we build software. Principles over tools, progressive abstraction, and craftsmanship.

Guide 10 min read 
  <a href="engineering-playbook/" class="doc-card">
    <h4 class="card-title">Engineering Playbook</h4>
    <p class="card-description">
      Practices, rituals, and processes. From code standards to incident response.
    </p>
    <div class="card-meta">
      <span class="card-meta-item">Guide</span>
      <span class="card-meta-item">30 min read</span>
    </div>
  </a>

  <a href="naming-conventions/" class="doc-card">
    <h4 class="card-title">Naming Conventions</h4>
    <p class="card-description">
      Style guide for JavaScript, TypeScript, Python, and Go. File naming and best practices.
    </p>
    <div class="card-meta">
      <span class="card-meta-item">Reference</span>
      <span class="card-meta-item">10 min read</span>
    </div>
  </a>
</div>

Why These Docs Exist

Documentation as a force multiplier for engineering teams.

Faster Onboarding

New engineers ship their first PR in days, not weeks. Clear guides eliminate guesswork.

Consistent Standards

Everyone follows the same patterns. Code reviews are faster. Codebases are more maintainable.

Shared Understanding

Documentation captures tribal knowledge. What one person learns, everyone can benefit from.

Additional Resources

Internal Links

  <div class="quick-links">
    <h4 class="quick-links-title">Tools &amp; Automation</h4>
    <ul class="link-list">
      <li class="link-item">
        <a href="pre-commit-setup/">
          <span>Pre-commit Hooks Setup</span>
          <span class="link-arrow">→</span>
        </a>
      </li>
      <li class="link-item">
        <a href="/">
          <span>CI/CD Pipeline Docs</span>
          <span class="link-arrow">→</span>
        </a>
      </li>
      <li class="link-item">
        <a href="/">
          <span>Monitoring &amp; Alerts Setup</span>
          <span class="link-arrow">→</span>
        </a>
      </li>
    </ul>
  </div>

  <div class="quick-links">
    <h4 class="quick-links-title">Need Help?</h4>
    <ul class="link-list">
      <li class="link-item">
        <a href="https://chat.google.com/app/home">
          <span>Ask in #all-engineers</span>
          <span class="link-arrow">→</span>
        </a>
      </li>
      <li class="link-item">
        <a href="/">
          <span>Schedule Office Hours</span>
          <span class="link-arrow">→</span>
        </a>
      </li>
      <li class="link-item">
        <a href="/">
          <span>Submit Feedback</span>
          <span class="link-arrow">→</span>
        </a>
      </li>
      <li class="link-item">
        <a href="/">
          <span>Propose Doc Changes</span>
          <span class="link-arrow">→</span>
        </a>
      </li>
    </ul>
  </div>
</div>

Doc Index

Edit this page

Engineering Cheat Sheet

Essential principles, conventions, and decision guides for daily development work.

Version 1.1 · Last Updated December 2025 · Print for Quick Reference

Core Engineering Beliefs

Principles Over Tools

Deep understanding matters more than superficial mastery of frameworks. Concepts drive tool choices.

Progressive Abstraction

Build simple first, then abstract. Avoid premature optimization that obscures clarity.

Code as Craft

Write for humans first. Clean, understandable code shows respect for future readers.

Document to Scale

Documentation is an act of generosity to teammates and your future self.

Speed with Stability

Move fast without shipping broken things. Testing and reviews safeguard quality.

Ownership Mentality

If you ship it, you own it. Monitor, maintain, and improve what you build.

Non-Negotiables

  • Every pull request gets reviewed. No self-merges. Feedback must be kind, clear, and constructive.
  • Tests are mandatory. 80% coverage target for core services. No broken code in main branches.
  • Never commit secrets. Use environment variables and secrets managers. Check before pushing.

Naming Conventions

JavaScript / TypeScript

  • Variables: camelCase
  • Functions: camelCase
  • Components: PascalCase
  • Constants: SCREAMING_SNAKE_CASE
  • Files: kebab-case

Python

  • Variables: snake_case
  • Functions: snake_case
  • Classes: PascalCase
  • Constants: SCREAMING_SNAKE_CASE
  • Files: kebab-case

Go

  • Variables: camelCase
  • Functions: camelCase
  • Exported Types: PascalCase
  • Packages: lowercase
  • Files: kebab-case

Decision Guide

Should I ship without tests? No. Write at least unit tests for business logic. Integration tests for user-facing features.

Should I self-merge my PR? No. Get one approval minimum, unless you’re a tech lead handling an emergency hotfix.

Should I abstract this code? Only if you’ve used it three or more times. Build simple first, abstract later.

Should I skip documentation? No. At minimum: what it does, how to run it, and any known issues.

Should I deploy to production? Only after dev → staging → tech lead approval. Monitor for at least one hour after.

Should I refactor this duplicated code? Yes, now. Don’t postpone improvements. Make the codebase better every time you touch it.

Development Workflow

  1. Start with Why — Understand the user need before writing code. Link to issues or document the requirement.

  2. Design Before Code — Think through architecture first. Draw diagrams or write brief design docs for complex features.

  3. Build Simple — Start with the simplest implementation. Avoid premature optimization or abstraction.

  4. Test Thoroughly — Write tests that cover happy paths and edge cases. Run locally before pushing.

  5. Refactor as You Go — Clean up duplicated code and unclear logic immediately while context is fresh.

  6. Submit for Review — Use PR template. Include clear description, screenshots for UI, and test instructions.

  7. Address Feedback — Respond within 24 hours. Make changes or discuss alternatives. Reviews are collaborative.

  8. Monitor After Deploy — Watch logs and metrics for at least one hour. Address issues quickly or revert if needed.

These aren’t rules to slow you down—they’re guardrails to help you move faster, together.

Edit this page

Development Workflow

A systematic approach to building, reviewing, and shipping code at Orcta.

Core Workflow

1. Start with Why

Every feature begins with understanding the user need or pain point being addressed.

Before writing code, clarify the problem space. Link to the relevant issue or ticket. If none exists, document the user story or requirement first.

Reference: Engineering Philosophy, Section 3

2. Design Before Implementation

Think through architecture and approach before the first line of code.

For small changes, outline your approach in comments or notes. For larger features, write a brief design document or create a diagram. Share with the team for early feedback.

Reference: Engineering Philosophy, Section 3

3. Build Simple, Then Abstract

Start with the simplest implementation that solves the problem.

Avoid premature optimization or abstraction. If you find yourself building for hypothetical future requirements, step back and focus on the current need. Abstractions emerge naturally after patterns repeat.

Reference: Engineering Philosophy, Section 2

4. Test Your Implementation

Write tests that validate both happy paths and edge cases.

Unit tests for business logic are required. Integration tests for user-facing features are expected. Aim for 80% coverage on core services. Run tests locally before committing.

Reference: Engineering Playbook, Section 7

5. Refactor as You Go

Improve code quality incrementally rather than accumulating technical debt.

When you encounter duplicated code, unclear naming, or confusing logic, fix it immediately. The best time to refactor is when the context is fresh in your mind.

Reference: Engineering Philosophy, Section 3

6. Submit for Review

Create a pull request with clear description and context.

Use the PR template. Include what changed, why it changed, and how to test. Link to related issues. Add screenshots for UI changes. Request review from at least one team member.

Reference: Engineering Playbook, Section 5

7. Address Feedback

Engage with reviewer comments thoughtfully and promptly.

Respond to all feedback within 24 hours. If you disagree with a suggestion, explain your reasoning. Make requested changes or discuss alternatives. Reviews are collaborative, not adversarial.

Reference: Engineering Playbook, Section 5

8. Monitor After Deploy

Track your changes in production to catch issues early.

After merging, monitor logs and metrics for at least one hour. Set up relevant alerts if needed. If issues arise, address them quickly or revert. Ownership extends beyond the merge button.

Reference: Engineering Playbook, Section 6

Deployment Environments

Development → Staging → Production

  • Development: Active development and testing
  • Staging: Pre-production validation
  • Production: Live user traffic

Every change flows through all three environments. Deploy to development freely for testing. Deploy to staging after tests pass. Deploy to production only with tech lead approval after staging validation.

Reference: Engineering Playbook, Section 6

Code Review Principles

Focus on Clarity

Code should be understandable by someone unfamiliar with the context. Prioritize readability over cleverness.

Assume Positive Intent

Approach reviews collaboratively. Authors did their best. Reviewers want to help improve the code.

Be Specific

Vague feedback like “this could be better” is not helpful. Point to specific lines and suggest concrete improvements.

Ask Questions

When uncertain about an approach, ask why rather than demanding changes. Understanding comes first.

Reference: Engineering Playbook, Section 5

Pre-Submission Checklist

  • All tests pass locally
  • Linter shows no errors
  • Code follows naming conventions
  • New functionality includes tests
  • Documentation updated where relevant
  • No secrets or credentials committed
  • Commit messages are descriptive
  • PR description explains what and why

Reference: Engineering Playbook, Section 5.2

Naming Conventions

JavaScript & TypeScript

  • Variables: camelCase
  • Functions: camelCase
  • Components: PascalCase
  • Constants: SCREAMING_SNAKE_CASE
  • Files: kebab-case

Python

  • Variables: snake_case
  • Functions: snake_case
  • Classes: PascalCase
  • Constants: SCREAMING_SNAKE_CASE
  • Files: kebab-case

Go

  • Variables: camelCase
  • Exported Types: PascalCase
  • Packages: lowercase
  • Files: kebab-case

Reference: Naming Conventions Guide, Section 2

Edit this page

Git Workflow: React Development

A practical guide for working with the Orcta React template.

Repository: Orctatech-Engineering-Team/orcta-react-template

Branching Model

We follow a simplified Git Flow that prioritizes clarity and reduces merge conflicts. All feature work happens in isolated branches that merge back to development.

Branch Structure

  • main → Production-ready code. Protected branch. Only tech leads can merge.
  • dev → Integration branch. All features merge here first for testing.
  • feature/* → Individual feature branches. Created from dev, merged back to dev.
  • hotfix/* → Emergency fixes. Created from main, merged to both main and dev.

Reference: Engineering Playbook, Section 4.2

Complete Workflow

Step 1: Clone and Setup

Start by creating your project from the React template on GitHub. Go to the template repository, select “Use this template”, create your new repository, then clone it to your machine.

# After creating your repo from the template
# Clone the newly generated repository
git clone git@github.com:Orctatech-Engineering-Team/YOUR-NEW-REPO.git

cd YOUR-NEW-REPO

# Install dependencies
pnpm install

# Verify the setup
pnpm run dev
pnpm test

First Time Setup: Ensure you have Node.js 20+ and pnpm 10+ installed. The template includes pre-configured ESLint, Prettier, and TypeScript settings. Run the linter with npm run lint before committing.

Step 2: Create a Feature Branch

Always create a new branch from the latest dev branch. Never work directly on main or dev.

# Switch to dev and get latest changes
git checkout dev
git pull origin dev

# Create your feature branch
git checkout -b feature/user-authentication

Branch Naming Convention: Use descriptive kebab-case names: feature/user-profile-page, feature/payment-integration, hotfix/login-redirect-bug

Step 3: Develop Your Feature

Build your feature following React best practices and the template’s folder structure.

src/
  components/
    user-profile/
      user-profile.tsx
      user-profile.test.tsx
      user-profile.module.css

Conventions:

  • Component names use PascalCase but their file names are kebab-case: user-profile.tsx
  • Component folders use kebab-case: user-profile/
  • Test files match component names: user-profile.test.tsx
  • CSS modules use kebab-case: user-profile.module.css

Reference: Naming Conventions Guide, Section 2.4

Step 4: Commit Your Changes

Make atomic commits with clear, descriptive messages in imperative mood.

# Stage your changes
git add src/components/user-profile/

# Commit with descriptive message
git commit -m "Add user profile component with avatar display"

Good Commits:

  • Add user authentication form
  • Fix navigation menu overflow on mobile
  • Update API endpoint for user profiles
  • Refactor payment form validation logic

Bad Commits:

  • Fixed stuff
  • Update
  • WIP
  • asdfasdf
  • Added feature and fixed bug and updated docs

Reference: Engineering Playbook, Section 4.1

Step 5: Keep Your Branch Updated

Regularly sync your feature branch with dev to minimize merge conflicts.

# Fetch latest changes from dev
git fetch origin dev

# Rebase your feature branch on top of dev
git rebase origin/dev

# If conflicts occur, resolve them and continue
# Edit conflicted files, then:
git add .
git rebase --continue

Rebase vs Merge: We prefer rebasing feature branches to maintain a linear history. This keeps the commit log clean and makes it easier to understand the evolution of the codebase. Only merge when integrating into dev or main.

Step 6: Run Tests and Linting

Ensure all tests pass and code meets quality standards before pushing.

# Run tests
pnpm test

# Run linter
pnpm run lint

# Fix auto-fixable linting issues
pnpm run lint:fix

# Check TypeScript types
pnpm run type-check

# Build to verify no errors
pnpm run build

Pre-commit Hooks: The template includes Husky pre-commit hooks that automatically run linting and tests. If these checks fail, the commit will be blocked. Fix the issues before committing.

Step 7: Push Your Branch

Push your feature branch to the remote repository.

# Push your branch for the first time
git push -u origin feature/user-authentication

# Subsequent pushes (after first push)
git push

# Force push after rebasing (use with caution)
git push --force-with-lease

Force Pushing: Use --force-with-lease instead of --force when you need to force push after rebasing. This prevents accidentally overwriting someone else’s work if they’ve pushed to your branch.

Step 8: Create a Pull Request

Open a pull request from your feature branch to dev. Use the PR template.

# Via GitHub CLI (if installed)
gh pr create --base dev --title "Add user authentication"

# Or visit GitHub and create PR manually
# The PR template will auto-populate

PR Requirements:

  • Base branch should always be dev (not main)
  • Fill out all sections of the PR template
  • Link to related issues or tickets
  • Add screenshots for UI changes
  • Request review from at least one team member
  • Add appropriate labels: feature, bug fix, refactor, etc.

Reference: Engineering Playbook, Section 4.3

Step 9: Address Review Feedback

Respond to reviewer comments and make requested changes.

# Make changes based on feedback
# Edit files, then commit
git add .
git commit -m "Address review feedback: improve error handling"

# Push changes
git push

# PR will automatically update

Review Etiquette: Respond to all comments, even if just to acknowledge. If you disagree with a suggestion, explain your reasoning respectfully. Mark conversations as resolved once addressed. Reviewers should respond within 48 hours.

Reference: Engineering Playbook, Section 5.3

Step 10: Merge and Clean Up

Once approved, merge your PR and delete the feature branch.

# After PR is approved and CI passes
# Merge via GitHub UI (squash commits)

# Then locally, clean up your branch
git checkout dev
git pull origin dev

# Delete local feature branch
git branch -d feature/user-authentication

# Delete remote branch (usually auto-deleted by GitHub)
git push origin --delete feature/user-authentication

Merge Strategy: We use squash merging to keep the dev and main branches clean. All commits from your feature branch are combined into a single commit. Write a clear merge commit message that summarizes the entire feature.

Reference: Engineering Playbook, Section 4.3

Common Scenarios

Scenario: Working on Multiple Features

You’re working on a user profile feature, but need to start a hotfix for a critical bug.

# Commit your current work
git add .
git commit -m "WIP: user profile layout"

# Switch to main for hotfix
git checkout main
git pull origin main
git checkout -b hotfix/login-redirect

# Fix bug, commit, and create PR
# After hotfix is merged, return to feature
git checkout feature/user-profile

Scenario: Merge Conflict During Rebase

You’re rebasing your feature branch and encounter conflicts.

git rebase origin/dev

# Git shows conflicts in specific files
# Open conflicted files and look for markers:
# <<<<<<< HEAD
# Your changes
# =======
# Their changes
# >>>>>>>

# Edit files to resolve conflicts
# Remove conflict markers
# Keep the correct code

git add .
git rebase --continue

# If you want to abort the rebase
git rebase --abort

Scenario: Accidentally Committed to Wrong Branch

You made commits to dev instead of a feature branch.

# Currently on dev with uncommitted changes
# Create feature branch from current state
git checkout -b feature/my-feature

# Go back to dev and reset it
git checkout dev
git reset --hard origin/dev

# Your changes are now safely in feature branch
git checkout feature/my-feature

Scenario: Need to Update PR After Rebase

You rebased your feature branch and need to update the PR.

# After rebasing
git rebase origin/dev

# Force push with safety check
git push --force-with-lease

# PR will automatically update
# Add a comment explaining the rebase

Quick Reference Commands

# Check current branch and status
git status
git branch

# View commit history
git log --oneline --graph

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Discard local changes
git checkout -- .

# Stash changes temporarily
git stash
git stash pop

# View diff before committing
git diff

# Amend last commit message
git commit --amend

# List all branches
git branch -a

# Clean up deleted remote branches
git fetch --prune
Edit this page

Pull Request Guidelines

What to include in every pull request. Checklist for authors and guidelines for reviewers.

PR Template Overview

Every pull request at Orcta uses a standard template to ensure consistency, clarity, and thoroughness. The template guides authors through documenting their changes and helps reviewers understand the context quickly.

Standard Template Structure

Summary Brief description of what this PR does in 2-3 sentences. Focus on the what, not the how.

Motivation Why are we making this change? Link to the issue or ticket, or explain the user need if no issue exists.

Changes Made List the key changes in this PR. Helps reviewers understand scope at a glance.

Testing Instructions Step-by-step guide for reviewers to verify the changes work as expected.

Screenshots or Evidence For UI changes: before and after screenshots. For backend: test output or API responses.

Pre-Submission Checklist Items to verify before requesting review. Ensures quality standards are met.

Technical Decisions Document trade-offs, alternative approaches considered, or technical debt introduced.

Related Work Links to dependent PRs, related issues, or follow-up work.

Reviewer Notes Specific areas where you want focused feedback or context that helps reviewers.

Reference: Engineering Playbook, Section 5.2

Author Checklist

Complete all items before requesting review. These checks ensure your PR meets quality standards and is ready for team review.

  • Tests pass locally — Run the full test suite before pushing
  • Linter passes — No ESLint, Flake8, or golangci-lint errors
  • Tests added or updated — New functionality includes corresponding tests
  • Naming conventions followed — Code follows language-specific style guide
  • Documentation updated — README, inline comments, or Notion docs reflect changes
  • No secrets committed — Verify with git diff before pushing
  • Code refactored — Left the codebase better than you found it

Pre-commit Hooks: Many of these checks run automatically via pre-commit hooks. If hooks fail, fix the issues before committing.

Writing Effective PR Descriptions

Good Summary

“Add user authentication with email and password. Implements login form, session management, and protected routes. Users can now sign in and access their profile pages.”

Bad Summary

“Added some auth stuff and fixed a few things. Should work now.”

What makes a good summary? Be specific about what changed. Include the scope and impact. Write for someone who wasn’t involved in the work. Avoid vague terms like “fixed stuff” or “updated things.”

Good Testing Instructions

  1. Start the dev server with npm run dev
  2. Navigate to /login
  3. Enter test@example.com / password123
  4. Verify redirect to /dashboard
  5. Check session persists on page refresh

Bad Testing Instructions

“Just test the login feature. Should be obvious.”

What makes good testing instructions? Step-by-step clarity. Include specific values to test with. Explain what success looks like. Don’t assume reviewers know your feature intimately.

Guidelines for Reviewers

Code review is a collaborative process to improve code quality and share knowledge. Reviews should be thorough but kind, constructive but efficient.

What to Review

  • Correctness of the implementation
  • Code readability and clarity
  • Test coverage and quality
  • Edge cases and error handling
  • Performance implications
  • Security considerations
  • Adherence to conventions

How to Review

  • Respond within 48 hours
  • Start with what works well
  • Ask questions before demanding changes
  • Be specific in your feedback
  • Suggest alternatives, don’t just criticize
  • Focus on substance over style
  • Assume positive intent

Reference: Engineering Playbook, Section 5.3

Feedback Best Practices

Effective Feedback

“This function could be more readable. Consider extracting the validation logic into a separate helper function. That would make it easier to test and reuse.”

Ineffective Feedback

“This is messy. Refactor it.”

What makes feedback effective? Point to specific lines or sections. Explain why something matters. Suggest concrete alternatives. Frame as collaboration, not criticism.

Constructive Question

“I notice we’re not handling the case where the API returns a 429. Is rate limiting handled elsewhere, or should we add retry logic here?”

Unconstructive Demand

“You forgot error handling. Add it.”

When to ask vs tell? Ask questions when you’re uncertain or want to understand the author’s reasoning. Make direct suggestions for clear improvements. Frame as collaboration whenever possible.

Common Review Patterns

Nitpick Pattern

For minor style or preference issues that don’t affect functionality, prefix with “Nit:” to indicate it’s not blocking. Example: “Nit: This variable name could be more descriptive, but not critical.”

Blocking vs Non-Blocking

Be clear about what must be fixed before merge versus what could be done in a follow-up. Use labels like “Blocking:” for critical issues and “Follow-up:” for nice-to-haves.

Learning Opportunity

Use reviews to teach and learn. Share relevant documentation, patterns, or examples. Explain the reasoning behind suggestions so authors understand the principles, not just the fixes.

Response Timeline

Timely reviews keep development moving and prevent context switching.

For Reviewers

  • First response within 48 hours
  • Subsequent reviews within 24 hours
  • If you can’t review, say so early
  • Unblock authors by reviewing incrementally
  • Prioritize reviews during maker hours

For Authors

  • Address feedback within 24 hours
  • Respond to all comments, even simple “Done”
  • Explain if you disagree with feedback
  • Mark conversations as resolved when fixed
  • Request re-review when ready

When Reviews Stall: If feedback sits unaddressed for 3+ days, or a PR waits for review beyond 48 hours, escalate to a tech lead. Sometimes a quick sync call can resolve blockers faster than async comments.

Approval and Merge

Approval Requirements

At least one approval required from a team member. For significant architectural changes, get approval from a tech lead. All CI checks must pass before merging.

Merge Strategy

We use squash merging to keep git history clean. All commits from your feature branch combine into one. Write a clear merge commit message that summarizes the entire feature.

After Merge

Monitor your changes in production for at least one hour. Delete your feature branch. Close related issues. Update documentation if needed.

Reference: Engineering Playbook, Section 4.3

Philosophy

Code review is about improving code, not judging people. We assume positive intent, engage collaboratively, and recognize that everyone is learning. Great reviews make the code better and help everyone grow as engineers.

Edit this page

Playbook in Practice

Real stories from Orcta Engineering. Learn from what went well and what didn’t.

Story One: The Minimum Lovable Product That Launched in Two Weeks

Context

Product requested a comprehensive user dashboard with fifteen distinct features. The initial timeline was set for one month of development work. The team needed to deliver value quickly while managing scope.

What We Did

  • Asked the fundamental question: what is the one thing users need most?
  • Shipped just the critical metrics view in the first week
  • Gathered real user feedback on actual usage patterns
  • Added three more features in week two based on observed behavior
  • Delivered a complete, usable product on schedule

Outcome

  • Users engaged heavily with the initial release
  • Data showed 60% of originally planned features were unnecessary
  • Saved three weeks of engineering time
  • Delivered higher-quality features informed by real usage

Key Lesson

Start with why and validate with real users before building everything. Assumptions about user needs are often wrong until tested.

Engineering Philosophy: Minimum Lovable Product — Build the smallest version users can love

Story Two: The Code Review That Prevented a Critical Bug

Context

A pull request introduced payment processing functionality. All tests passed. The implementation appeared sound on first inspection. The PR was ready for approval.

What Happened

During review, an engineer noticed missing error handling for network failures. They asked a simple question: what happens if the payment API times out?

The author realized users would be charged but orders wouldn’t be recorded in our system. A critical data integrity issue that would have caused significant problems in production.

What We Did

  • Added retry logic with exponential backoff for transient failures
  • Implemented transaction rollback on payment confirmation failure
  • Created integration tests specifically for timeout scenarios
  • Documented the edge case for future reference

Outcome

  • Caught a critical bug before it reached production
  • Prevented potential revenue loss and customer trust issues
  • Improved the payment system’s overall reliability
  • Created reusable patterns for similar integrations

Key Lesson

Code reviews aren’t about finding typos. They’re about protecting users and the business by thinking through edge cases together.

Engineering Playbook, Section 5: Code reviews are sacred — feedback must be kind, clear, and focused on improvement

Story Three: When We Ignored Refactor as You Go

Context

While building a new API endpoint, an engineer noticed duplicated authentication logic across five different controllers. The code worked, but the duplication was obvious.

What We Did Wrong

The team decided to ship quickly with a note: we’ll refactor later when we have time. The authentication code was copied one more time. Development continued.

Three months passed. A security vulnerability was discovered in the authentication logic. The fix needed to be applied in six different places across the codebase.

The Incident

Two instances of the duplicated code were missed during the fix. Production experienced a two-hour outage when those endpoints were exploited. Customer data was not compromised, but trust was shaken.

What We Should Have Done

Invested thirty minutes to extract the authentication logic into a reusable middleware component. Fixed it once, used it everywhere. The vulnerability would have required one change in one place.

Outcome

  • Two-hour production outage affecting all users
  • Emergency incident response requiring all-hands effort
  • Blameless postmortem conducted within 48 hours
  • New team agreement: refactor duplicated code immediately

Key Lesson

Later usually means never. Technical debt compounds. What takes thirty minutes today costs ten times that in three months, plus the cost of the incident.

Engineering Philosophy, Section 3: Refactor as you go — Don’t postpone improvements

Story Four: The Documentation That Unblocked Three Teams

Context

A new internal API for user permissions was built and deployed. No formal documentation was written. Information was shared through Slack messages and verbal explanations.

What Happened

Over the next month, three different teams needed to integrate with the permissions API. Each team reached out with similar questions about authentication, endpoint structure, and error handling.

The original author spent over six hours answering repetitive questions in Slack DMs and ad-hoc meetings. Integration took each team longer than necessary due to missing context.

What We Did to Fix It

Invested fifteen minutes writing a clear README with essential information:

  • What the API does and why it exists
  • How to authenticate and handle tokens
  • Three common use cases with code examples
  • Known limitations and error scenarios
  • Inline code comments for complex logic

Outcome

  • Repetitive questions stopped immediately
  • Teams integrated independently without blocking the author
  • README was referenced over forty times in two months
  • Onboarding new engineers to the system became trivial

Key Lesson

Fifteen minutes of documentation saves ten hours of interruptions. Documentation is generosity to your teammates and your future self.

Engineering Philosophy, Section 2: Document to scale — Documentation is an act of generosity

Story Five: The Postmortem That Made Us Better

Context

Production database ran out of connections during peak traffic. The site went down for forty-five minutes. Users couldn’t access the application. Support tickets flooded in.

What We Did

Held a blameless postmortem within forty-eight hours of resolution. The team asked five whys to understand root causes:

Five Whys Analysis:

Why did the database run out of connections? Connection pool wasn’t sized correctly for peak load.

Why wasn’t it sized correctly? We didn’t load test before launch.

Why didn’t we load test? No documented process or checklist for pre-launch testing.

Why no process? Never formalized what everyone assumed was known.

Why wasn’t it formalized? Tribal knowledge instead of written procedures.

Actions Taken

  • Created comprehensive pre-launch checklist including load testing
  • Set up database connection monitoring with alerts
  • Documented runbook for connection pool issues
  • Made pre-launch checklist mandatory via PR template
  • Scheduled quarterly review of operational procedures

Outcome

  • No similar incidents in the following six months
  • Pre-launch checklist caught two other potential issues
  • Team felt safe discussing mistakes without blame
  • Culture of learning from failure was strengthened

Key Lesson

Systems fail. Humans make mistakes. How we respond to failure defines our culture. Blameless analysis and systematic improvement matter more than perfect execution.

Engineering Philosophy, Section 3: Fail fast, learn faster — Mistakes are okay, cover them in postmortems

Story Six: When Ownership Meant Heroism

Context

An engineer deployed a new feature Friday evening. At eleven PM, they received a page about a bug in production. The feature had an edge case that wasn’t caught in testing.

What Happened

The engineer felt personally responsible. They believed ownership meant solving it alone. They stayed up until two AM debugging and deploying a fix. The issue was resolved but the engineer was exhausted.

The following week, they felt burned out. Work-life balance suffered. The incident response, while successful, wasn’t sustainable.

What We Should Have Done

  • The on-call engineer should have handled the initial response
  • If the feature author wanted to help, pair with on-call instead of solo work
  • For critical issues, wake the tech lead for support and guidance
  • Follow established incident response procedures
  • No one should feel obligated to sacrifice sleep

What We Changed

  • Clarified that ownership doesn’t mean martyrdom
  • Set clear on-call expectations and rotation schedules
  • Added retro question: did anyone feel unsupported this week?
  • Emphasized collaborative incident response in documentation
  • Leadership modeled asking for help publicly

Outcome

  • Better work-life balance across the team
  • More effective collaborative incident response
  • Reduced individual stress and burnout
  • No one felt guilty for asking for help

Key Lesson

Ownership means responsibility, not isolation. We own problems collectively, not individually. Sustainable engineering requires sustainable practices.

Engineering Philosophy, Section 2: Ownership mentality — But we own problems collectively

How to Use These Stories

In Code Reviews

Reference relevant stories when providing feedback. “This reminds me of Story Two—can we add error handling here?”

In Standups

Connect current work to past lessons. “Feels like Story Three—should we refactor now before it spreads?”

In Retrospectives

Use stories to frame discussions. “This situation is similar to Story Four—let’s document this so it doesn’t happen again.”

In Onboarding

Share stories with new engineers to explain why the playbook exists and how principles apply in practice.

Add Your Own Stories

Saw something that reinforces or challenges our principles? Share it. These stories are our institutional knowledge.

  1. Write it up using the format: Context, What Happened, Outcome, Key Lesson
  2. Post in the engineering Slack channel for discussion
  3. Submit a pull request to add it to this document
  4. Share the lesson in the next team meeting
Edit this page

Onboarding Checklist

A lightweight 90-day plan for new engineers to ramp up, build context, and take ownership.

Days 1-7: Foundations

  • Set up local dev environment and access required tools.
  • Read the Engineering Cheat Sheet and Development Workflow.
  • Meet your onboarding buddy and identify a starter task.

Days 8-30: Contribution

  • Ship at least one scoped change with a full PR.
  • Pair on a medium-sized task to learn team patterns.
  • Document one unclear process you encounter.

Days 31-60: Ownership

  • Own a feature or component end-to-end.
  • Improve tests or reliability in an existing area.
  • Present a short demo or write-up of what you shipped.

Days 61-90: Deepening Impact

  • Identify a meaningful system improvement and propose a plan.
  • Lead a PR review or small release.
  • Align with your manager on growth goals for the next quarter.
Edit this page

Engineering Philosophy

Our philosophy anchors how we design, build, and ship.

Principles

  • Principles over tools: pick the best tool for the job, but protect the fundamentals.
  • Progressive abstraction: start simple, abstract only when patterns repeat.
  • Craftsmanship: readable, reliable systems beat clever shortcuts.
  • Human experience: performance and reliability must serve real users.
Edit this page

Engineering Playbook

A shared set of practices, rituals, and standards that keep delivery consistent.

Core Practices

  • Design before implementation for anything beyond a small change.
  • Write tests for business logic and user-facing behavior.
  • Review for clarity, correctness, and maintainability.
  • Monitor production after releases and document outcomes.

Rituals

  • Weekly planning and scope alignment.
  • Code reviews within 48 hours.
  • Post-release checks on critical systems.
Edit this page

Naming Conventions

Keep naming consistent so the codebase stays readable across teams.

JavaScript & TypeScript

  • Variables: camelCase
  • Functions: camelCase
  • Components: PascalCase
  • Constants: SCREAMING_SNAKE_CASE
  • Files: kebab-case

Python

  • Variables: snake_case
  • Functions: snake_case
  • Classes: PascalCase
  • Constants: SCREAMING_SNAKE_CASE
  • Files: kebab-case

Go

  • Variables: camelCase
  • Exported Types: PascalCase
  • Packages: lowercase
  • Files: kebab-case
Edit this page

Pre-commit Hooks Setup

Use the repo’s default tooling to run checks locally before you open a PR.

Standard Setup

  1. Read the project README for stack-specific steps.
  2. Install dependencies (example: pnpm install or npm install).
  3. If the repo uses pre-commit, run pre-commit install.
  4. Run the full check once: pre-commit run --all-files.

Expectations

  • Fix lint and formatting issues before committing.
  • Keep the hook configuration in the repo, not in local overrides.
Edit this page

Infrastructure

Operational documentation for Orcta production infrastructure and deployment workflows.

Edit this page

CI/CD Pipeline

This runbook explains how Orcta deploys services from GitHub to the VPS using GitHub Actions, Docker, and a shared PostgreSQL cluster.

High-Level Architecture

  • Codebase: GitHub (dev and main branches).
  • CI/CD: GitHub Actions (SSH deploy to VPS).
  • Runtime: Ubuntu VPS running Docker + Docker Compose.
  • Services:
    • App containers per repo.
    • Shared PostgreSQL cluster (Dockerized) with per-app DBs/roles.
    • Caddy reverse proxy for routing and TLS (optional).

Deployment Flow

  1. Push to main or dev.
  2. GitHub Actions connects to the VPS via SSH.
  3. The repo is cloned or pulled into /srv/apps/<APP>.
  4. Docker Compose rebuilds and restarts the service.
  5. Caddy reloads to pick up new routes.

Architecture Diagram

             ┌───────────────────────┐
             │       GitHub Repo     │
             │  (main & dev branches)│
             └───────────┬───────────┘
                         │
                    Push triggers
                         │
                         ▼
             ┌───────────────────────┐
             │    GitHub Actions     │
             │  (CI/CD Workflows)    │
             └───────────┬───────────┘
                         │
                   SSH Deploys to
                         │
                         ▼
    ┌─────────────────────────────────────────┐
    │                 VPS                     │
    │   (Ubuntu + Docker + Docker Compose)    │
    │                                         │
    │  ┌───────────────────────────────────┐  │
    │  │      Shared Docker Network        │  │
    │  │         `orcta-net`               │  │
    │  │                                   │  │
    │  │  ┌─────────────┐   ┌────────────┐ │  │
    │  │  │   app1      │   │   app2     │ │  │
    │  │  │ dockerized  │   │ dockerized │ │  │
    │  │  │ service     │   │ service    │ │  │
    │  │  └─────┬───────┘   └──────┬─────┘ │  │
    │  │        │                  │       │  │
    │  │        ▼                  ▼       │  │
    │  │   postgres://app1_db   postgres://app2_db
    │  │                                   │  │
    │  │        ┌───────────────────┐      │  │
    │  │        │   PostgreSQL DB   │      │  │
    │  │        │   dockerized      │      │  │
    │  │        │   per-app roles   │      │  │
    │  │        └───────────────────┘      │  │
    │  └───────────────────────────────────┘  │
    │                                         │
    │ Backups → /srv/orcta/postgres/backups/  │
    └─────────────────────────────────────────┘

VPS Directory Layout

/srv/apps
  app1/
    docker-compose.yml
    Caddyfile-snippet
  app2/
    docker-compose.yml
    Caddyfile-snippet

/srv/orcta-postgres
  docker-compose.yml
  init/
    01-init.sql
  backups/
  backup.sh

GitHub Actions (Example)

.github/workflows/deploy.yml

name: CI/CD Pipeline (Direct VPS Build)

on:
  push:
    branches: [dev, main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Deploy on VPS
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: ${{ secrets.VPS_HOST }}
          username: ${{ secrets.VPS_USER }}
          key: ${{ secrets.VPS_SSH_KEY }}
          script: |
            set -e
            APP=orcta-app
            mkdir -p /srv/apps/$APP
            cd /srv/apps/$APP

            if [ ! -d ".git" ]; then
              git clone git@github.com:Orctatech-Engineering-Team/$APP.git .
            else
              git pull origin main
            fi

            docker compose up --build -d

PostgreSQL Setup

/srv/orcta-postgres/docker-compose.yml

version: "3.9"
services:
  postgres:
    image: postgres:16
    container_name: orcta_postgres
    restart: always
    environment:
      POSTGRES_PASSWORD: <set-in-env>
    volumes:
      - ./data:/var/lib/postgresql/data
      - ./init:/docker-entrypoint-initdb.d
    networks:
      - orcta_net

  pgbouncer:
    image: edoburu/pgbouncer
    container_name: orcta_pgbouncer
    restart: always
    ports:
      - "6432:6432"
    environment:
      DB_USER: pgbouncer
      DB_PASSWORD: <set-in-env>
      DB_HOST: postgres
      DB_PORT: 5432
      POOL_MODE: transaction
      MAX_CLIENT_CONN: 200
      DEFAULT_POOL_SIZE: 20
    depends_on:
      - postgres
    networks:
      - orcta_net

networks:
  orcta_net:
    external: true

Example init script (/srv/orcta-postgres/init/01-init.sql):

CREATE USER app1_user WITH PASSWORD '<password>';
CREATE DATABASE app1_db OWNER app1_user;
REVOKE ALL ON DATABASE app1_db FROM PUBLIC;

Caddy Reverse Proxy

Main /etc/caddy/Caddyfile:

{
    email admin@orctatech.com
}

import /srv/apps/*/Caddyfile-snippet

Example snippet:

orcta.example.com {
    reverse_proxy localhost:9999
}

Backups

/srv/orcta-postgres/backup.sh:

#!/bin/bash
TIMESTAMP=$(date +%F_%H-%M-%S)
docker exec -t orcta-postgres pg_dumpall -U postgres > /srv/orcta-postgres/backups/db_$TIMESTAMP.sql

Cron (2 AM daily):

0 2 * * * /srv/orcta-postgres/backup.sh

Monitoring & Troubleshooting

  • App logs: docker logs -f <container>
  • Postgres logs: docker logs -f orcta-postgres
  • Caddy logs: journalctl -u caddy --no-pager -n 100
Edit this page

VPS Setup & Hardening

This guide summarizes the initial setup and security hardening steps for a new Ubuntu VPS. The process is automated in an idempotent, interactive script.

Script Overview

The setup script performs the following:

  • Creates users and adds them to sudo.
  • Installs and configures SSH keys.
  • Disables password auth and root login.
  • Optionally changes the SSH port.
  • Installs and enables UFW, Fail2Ban, and unattended upgrades.
  • Logs output to /var/log/vps-setup.log.

Usage

sudo bash vps-setup.sh

Key Steps (Manual Reference)

System Updates

sudo apt update && sudo apt upgrade -y

SSH Hardening

  • PasswordAuthentication no
  • PermitRootLogin no
  • PubkeyAuthentication yes

Config file: /etc/ssh/sshd_config

Firewall

sudo apt install ufw -y
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw --force enable

Fail2Ban

sudo apt install fail2ban -y
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

Automatic Updates

sudo apt install unattended-upgrades -y
sudo dpkg-reconfigure -f noninteractive unattended-upgrades

Logging

All script output is written to /var/log/vps-setup.log with restricted permissions.

Troubleshooting

  • If SSH access breaks after changing ports, revert the port via console access.
  • Confirm SSH service is running: sudo systemctl status ssh.
Edit this page

Infrastructure Diagrams

Reference visuals for how our infrastructure and deployment flow fit together.

Deployment Flow

             ┌───────────────────────┐
             │       GitHub Repo     │
             │  (main & dev branches)│
             └───────────┬───────────┘
                         │
                    Push triggers
                         │
                         ▼
             ┌───────────────────────┐
             │    GitHub Actions     │
             │  (CI/CD Workflows)    │
             └───────────┬───────────┘
                         │
                   SSH Deploys to
                         │
                         ▼
    ┌─────────────────────────────────────────┐
    │                 VPS                     │
    │   (Ubuntu + Docker + Docker Compose)    │
    │                                         │
    │  ┌───────────────────────────────────┐  │
    │  │      Shared Docker Network        │  │
    │  │         `orcta-net`               │  │
    │  │                                   │  │
    │  │  ┌─────────────┐   ┌────────────┐ │  │
    │  │  │   app1      │   │   app2     │ │  │
    │  │  │ dockerized  │   │ dockerized │ │  │
    │  │  │ service     │   │ service    │ │  │
    │  │  └─────┬───────┘   └──────┬─────┘ │  │
    │  │        │                  │       │  │
    │  │        ▼                  ▼       │  │
    │  │   postgres://app1_db   postgres://app2_db
    │  │                                   │  │
    │  │        ┌───────────────────┐      │  │
    │  │        │   PostgreSQL DB   │      │  │
    │  │        │   dockerized      │      │  │
    │  │        │   per-app roles   │      │  │
    │  │        └───────────────────┘      │  │
    │  └───────────────────────────────────┘  │
    │                                         │
    │ Backups → /srv/orcta/postgres/backups/  │
    └─────────────────────────────────────────┘

Caddy Reverse Proxy

Internet
   │
   ▼
Caddy (TLS + routing)
   │
   ├── app1.orcta.example → localhost:9999
   └── app2.orcta.example → localhost:9998

Database Backup Flow

Postgres container
   │
   │ pg_dumpall
   ▼
/srv/orcta-postgres/backups/db_<timestamp>.sql
   │
   ▼
Offsite or cold storage (manual or scheduled)
Edit this page

Insights

Insights

Short essays, quotes, and operating philosophies that shape how Orcta builds and leads.

Explore

Capture the ideas that keep teams aligned and moving.

Operating Philosophies

Principles inspired by proven product teams, adapted to Orcta's context.

Quotes

Curated quotes that capture our thinking. Add new entries as they emerge.

Notes

Mini blog posts with lessons learned, decisions, and practical guidance.

Latest Notes

Recent posts with focus tags.

Start small, earn trust

Ship the smallest reliable solution, then expand.

product delivery reliability

Shipping with reliability

Treat stability as part of every release.

reliability engineering delivery

When to say no

Protect the roadmap by saying no to misaligned work.

product culture delivery

Index

Edit this page

Operating Philosophies

These principles are inspired by proven product and engineering practices (including 37signals-style thinking) and adapted for Orcta’s context.

Build the small thing first

Start with the smallest version that solves the real problem. Ship fast, learn from usage, and expand only when the need is clear.

Opinionated defaults beat endless options

Give users a strong, sane path. Configuration comes later, after patterns emerge.

Calm software is a competitive advantage

Systems should reduce stress, not add to it. Prioritize clarity, stability, and predictability over flashy features.

Reduce scope, then improve depth

When timelines compress, cut features before cutting quality. A tight, reliable product earns trust faster than a wide, fragile one.

One team, one source of truth

Documentation is part of the product. Keep it current, concise, and close to the work so decisions scale with the team.

Make the system easy to explain

If you cannot explain a system in a few sentences, it is too complex. Simplify the architecture until it becomes teachable.

Edit this page

Quotes

A running collection of quotes that capture how we think and build. Add new entries as individual files in this folder and link them here.

Edit this page

Quote Template

Quote: “”

Author:

Context: <when/why the quote was said>

Edit this page

Notes

Short internal posts that capture lessons learned, decisions, and practical guidance.

Edit this page

Start small, earn trust

Tags: product, delivery, reliability

The fastest way to earn trust is to ship a small, reliable solution that solves the core problem. Bigger launches can wait; reliability cannot.

What this looks like at Orcta

  • Ship a minimum scope release with real users in mind.
  • Measure outcomes before adding new features.
  • Keep the product simple enough that any engineer can explain it.
Edit this page

Shipping with reliability

Tags: reliability, engineering, delivery

Reliability is the feature that keeps customers. A release is not done until it is stable under real usage.

What this looks like at Orcta

  • Add monitoring or logs before pushing a risky change.
  • Prefer one clear path over multiple half-finished options.
  • Treat post-release checks as part of the job, not an extra step.
Edit this page

When to say no

Tags: product, culture, delivery

Saying no protects the roadmap. Every yes should move a real metric or user outcome.

What this looks like at Orcta

  • Decline requests that do not match the mission or user need.
  • Reduce scope when a deadline is fixed.
  • Trade experiments for validated wins if time is tight.
Edit this page

Note Template

Title: <short, specific headline>

Date: YYYY-MM-DD

Summary: 2-3 sentences on the main takeaway.

Context

What prompted this note? Include relevant project or decision context.

Takeaway

What should the team remember or do differently next time?

  • Link to supporting docs, issues, or PRs.
Edit this page

Tags

Use short, consistent tags to make notes easy to scan.

  • product
  • engineering
  • delivery
  • reliability
  • infra
  • design
  • customer
  • culture
Edit this page