From 2fa4184a328dae9d9e6a813ccf7df7f7cc8651f6 Mon Sep 17 00:00:00 2001 From: CEO Date: Mon, 22 Jun 2026 05:58:34 +0200 Subject: [PATCH] Engineering foundation: README, CONTRIBUTING, tech stack, ADR template, onboarding, CI placeholder, first engineer role Sets up the engineering baseline for El Foundation before product work begins. - README.md: project overview and repo layout - CONTRIBUTING.md: branch naming, PR process, commit style, definition of done - docs/engineering/tech-stack.md: frontend, backend, and tooling choices with rationale - docs/engineering/onboarding.md: 30-day onboarding checklist - docs/adrs/adr-template.md: decision record template - .github/workflows/ci.yml: markdown lint + placeholder for TypeScript checks - docs/engineering/first-engineer-role.md: scope, skills, 30-day priorities, hire recommendation Co-Authored-By: Paperclip --- .github/workflows/ci.yml | 33 +++++++++++ CONTRIBUTING.md | 78 +++++++++++++++++++++++++ README.md | 38 ++++++++++++ docs/adrs/adr-template.md | 51 ++++++++++++++++ docs/engineering/first-engineer-role.md | 70 ++++++++++++++++++++++ docs/engineering/onboarding.md | 43 ++++++++++++++ docs/engineering/tech-stack.md | 49 ++++++++++++++++ 7 files changed, 362 insertions(+) create mode 100644 .github/workflows/ci.yml create mode 100644 CONTRIBUTING.md create mode 100644 README.md create mode 100644 docs/adrs/adr-template.md create mode 100644 docs/engineering/first-engineer-role.md create mode 100644 docs/engineering/onboarding.md create mode 100644 docs/engineering/tech-stack.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 00000000..dd058840 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,33 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + lint-docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Check markdown formatting + uses: DavidAnson/markdownlint-cli2-action@v16 + with: + globs: '**/*.md' + continue-on-error: true + + # TODO: Enable once we have a TypeScript project + # lint-and-test: + # runs-on: ubuntu-latest + # steps: + # - uses: actions/checkout@v4 + # - uses: pnpm/action-setup@v4 + # - uses: actions/setup-node@v4 + # with: + # node-version: 22 + # cache: 'pnpm' + # - run: pnpm install --frozen-lockfile + # - run: pnpm lint + # - run: pnpm typecheck + # - run: pnpm test diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..676702b9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,78 @@ +# Contributing to El Foundation + +## One Task = One Branch = One Owner + +Every issue gets its own branch. Branch names follow this pattern: + +``` +owner-identifier/short-description +``` + +Examples: +- `cto/ELF-4-engineering-foundation` +- `eng-1/add-auth-middleware` + +## No Direct Commits to `main` + +All changes go through a pull request. No exceptions. + +## Pull Request Process + +1. **Open a PR** from your branch to `main`. +2. **Fill out the PR template** (risk, rollback, verification). +3. **Request review** from the relevant owner: + - Code changes → another engineer or CTO + - UX-facing changes → UXDesigner + - Security-sensitive changes → SecurityEngineer +4. **Address feedback** or escalate disagreements in writing. +5. **Ship on green.** Once CI passes and review is approved, the owner merges. + +## Commit Messages + +Commit messages explain **why**, not what. The diff shows what changed; the message explains the reasoning. + +Good: +``` +Add rotating refresh tokens + +Using a rotating refresh token strategy prevents replay attacks +and gives us a clean theft-detection signal. See ADR-003. + +Co-Authored-By: Paperclip +``` + +Bad: +``` +Update auth.ts +``` + +## Code Style + +- TypeScript strict. No `any` unless explicitly approved — use `unknown` + narrowing. +- Keep `lib/` (pure logic) and `services/` (I/O, DB, network) separate. +- Prefer small modules over clever abstractions. +- No comments unless the code is genuinely non-obvious or there is a real `// FIXME`. +- No defensive try/catch around things that should not fail. Let it throw. +- Server Components by default; reach for `"use client"` only when state, effects, or browser APIs are needed. + +## Definition of Done + +A task is not done until **all** of the following are true: + +1. Code is written and reviewed. +2. Tests pass. CI is green. +3. Documentation is updated. +4. No secrets in plain text. +5. User-facing changes are validated. +6. Rollback path is known. +7. Handoff is clean — follow-up work is captured in a new issue. + +## Security + +- Never commit secrets, credentials, or customer data. +- Security-sensitive changes (auth, crypto, secrets, permissions) require SecurityEngineer review before merging. +- Report vulnerabilities to the CTO immediately. + +## Questions? + +Open an issue or ask in the project channel. Async-first: write it down. diff --git a/README.md b/README.md new file mode 100644 index 00000000..3f4bb3e5 --- /dev/null +++ b/README.md @@ -0,0 +1,38 @@ +# El Foundation + +Engineering repository for El Foundation. + +## About + +El Foundation builds institutions that outlast their founders. We create technology and organizations that compound in value over time. This repository is the source of truth for our engineering work. + +## Getting Started + +1. Read the [company charter](docs/company/charter.md) to understand why we exist. +2. Read the [operating model](docs/company/operating-model.md) to understand how decisions are made. +3. Read [CONTRIBUTING.md](CONTRIBUTING.md) before making any changes. + +## Repository Layout + +``` +├── .github/workflows/ # CI/CD definitions +├── docs/ +│ ├── company/ # Founding documents (charter, org, etc.) +│ ├── engineering/ # Engineering standards and decisions +│ └── adrs/ # Architecture Decision Records +├── apps/ # Application code (TBD — created when product work begins) +├── packages/ # Shared libraries and packages +└── scripts/ # Automation and utility scripts +``` + +## Technology Stack + +See [docs/engineering/tech-stack.md](docs/engineering/tech-stack.md) for current choices and rationale. + +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md). + +## License + +Proprietary — All rights reserved. diff --git a/docs/adrs/adr-template.md b/docs/adrs/adr-template.md new file mode 100644 index 00000000..ec462c2a --- /dev/null +++ b/docs/adrs/adr-template.md @@ -0,0 +1,51 @@ +# ADR-XXX: Title + +## Status + +- Proposed +- Accepted +- Deprecated +- Superseded by [ADR-YYY](adr-YYY.md) + +## Context + +What is the problem or opportunity we are addressing? What forces are at play? + +## Decision + +What are we doing? Be specific. + +## Consequences + +### Positive + +- Benefit 1 +- Benefit 2 + +### Negative / Risks + +- Risk 1 +- Risk 2 + +## Alternatives Considered + +### Option A: [Name] + +- Pros: ... +- Cons: ... +- Why rejected: ... + +### Option B: [Name] + +- Pros: ... +- Cons: ... +- Why rejected: ... + +## Rollback Plan + +If this decision proves wrong, how do we undo it? + +## Related + +- [ADR-YYY](adr-YYY.md) +- [PR #123](../../pull/123) diff --git a/docs/engineering/first-engineer-role.md b/docs/engineering/first-engineer-role.md new file mode 100644 index 00000000..e17aa817 --- /dev/null +++ b/docs/engineering/first-engineer-role.md @@ -0,0 +1,70 @@ +# Role Definition: First Software Engineer + +## Context + +El Foundation has established its charter, operating model, and engineering baseline. We are pre-product but have a clear technical direction. The first engineer will work directly with the CTO to build the initial product and set the engineering culture for every hire that follows. + +## What They Will Own + +- **Product implementation.** Write the first lines of production code. Own features end-to-end from task assignment to merge. +- **Technical foundation.** Help solidify the stack, tooling, and conventions. The code you write sets the standard. +- **Quality bar.** Write tests, review PRs, and catch regressions before they reach users. +- **Documentation.** If it is not written down, it does not exist. Document APIs, runbooks, and decisions as you go. +- **Production reliability.** Once we have users, own on-call rotation with the CTO and ensure systems stay healthy. + +## Technical Skills Required + +### Must-Have + +- **TypeScript** — strong typed-language fundamentals, comfortable with strict mode +- **React / Next.js** — experience with App Router, Server Components, and modern React patterns +- **Relational databases** — schema design, query optimization, migration discipline (PostgreSQL preferred) +- **Git and GitHub** — branching, rebasing, PR discipline, code review +- **Testing mindset** — writes tests as a default, not an afterthought + +### Nice-to-Have + +- **Prisma ORM** — or similar type-safe ORM experience +- **Tailwind CSS** — or strong utility-first CSS experience +- **Monorepo tooling** — Turborepo, Nx, or similar +- **Cloud infrastructure** — Vercel, AWS, Fly.io, or similar +- **Authentication / security** — OAuth, JWT, session management +- **Mongolian language or market context** — our early users are likely in Mongolia + +## Attributes We Value + +- **Slope over intercept.** We care more about how fast you learn than what you already know. +- **Writes things down.** Async-first communication. Clear documentation. Decision records. +- **Disagrees and commits.** Healthy dissent, then full commitment once a decision is made. +- **Protects focus.** Ruthless prioritization. Says no to multitasking. +- **Pulls for bad news.** Surfaces problems early. Does not hide blockers. + +## First 30-Day Priorities + +| Week | Focus | Deliverable | +|---|---|---| +| 1 | Onboard and ship a small fix | Merged PR, environment verified | +| 2 | Build first feature slice | Working code in staging | +| 3 | Establish testing pattern | Test coverage for new code, CI green | +| 4 | Document and refine | Updated docs, onboarding feedback, first ADR contribution | + +## Reporting + +- **Reports to:** CTO +- **Peers:** None yet — you are the first IC +- **Growth path:** Senior Engineer → Staff Engineer → Engineering Lead as the team scales + +## Compensation & Logistics + +- **Decision owner:** CEO (pending approval) +- **Budget:** To be confirmed by CEO +- **Location:** Remote / async-first +- **Start date:** As soon as approved and hired + +## Recommendation + +**Hire a mid-level full-stack engineer with strong TypeScript and Next.js experience.** They should have shipped production code independently and be comfortable with ambiguity. A senior engineer would be ideal but may be overkill for our current stage and budget. A junior engineer would require too much hands-on guidance from the CTO, slowing both product velocity and hiring velocity. + +**Suggested title:** Software Engineer +**Suggested level:** Mid-level (2–5 years shipping production code) +**Priority:** High — we cannot build product without an engineer. diff --git a/docs/engineering/onboarding.md b/docs/engineering/onboarding.md new file mode 100644 index 00000000..e95672ab --- /dev/null +++ b/docs/engineering/onboarding.md @@ -0,0 +1,43 @@ +# Engineer Onboarding + +## Before Day 1 + +- [ ] Access to GitHub org granted +- [ ] Access to Paperclip workspace granted +- [ ] Added to project channels / async standup + +## Day 1: Context + +- [ ] Read the [company charter](../company/charter.md) +- [ ] Read the [operating model](../company/operating-model.md) +- [ ] Read [ways of working](../company/ways-of-working.md) +- [ ] Read [how we decide](../company/how-we-decide.md) +- [ ] Read [CONTRIBUTING.md](../../CONTRIBUTING.md) +- [ ] Read [tech-stack.md](tech-stack.md) +- [ ] Introduce yourself in the team channel (async written standup format) + +## Day 2–3: Environment + +- [ ] Clone the repo +- [ ] Install dependencies (`pnpm install` when package.json exists) +- [ ] Run the dev server locally +- [ ] Verify you can run tests +- [ ] Verify you can run lint +- [ ] Open your first PR (a README typo fix or doc improvement counts) + +## Week 1: First Task + +- [ ] Pick up a `good first issue` or grab a task from the backlog with CTO approval +- [ ] Follow the full task lifecycle: branch → PR → review → merge +- [ ] Shadow one code review as a reviewer (even if just observing) + +## First 30 Days + +- [ ] Ship at least one meaningful change to production (or equivalent if pre-launch) +- [ ] Write or update one piece of documentation +- [ ] Attend (async) one decision review or ADR discussion +- [ ] Provide feedback on the onboarding process itself + +## Questions? + +Ask the CTO or post in the project channel. Async-first: write it down. diff --git a/docs/engineering/tech-stack.md b/docs/engineering/tech-stack.md new file mode 100644 index 00000000..efed674a --- /dev/null +++ b/docs/engineering/tech-stack.md @@ -0,0 +1,49 @@ +# Technology Stack + +## Overview + +These choices were made by the CTO on 2026-06-22, aligned with the company charter and operating principles. They are reversible within a day for local development, but would require migration effort once production data exists. All choices default to boring, well-supported technology over novelty. + +## Frontend + +| Layer | Choice | Rationale | +|---|---|---| +| Framework | Next.js (App Router) | Full-stack React with SSR/SSG, API routes, and a large ecosystem. App Router is the stable future path. | +| Language | TypeScript (strict) | Catches entire classes of bugs at build time. Strict mode is non-negotiable. | +| Styling | Tailwind CSS | Utility-first, colocated with components, no separate CSS files to maintain. | +| UI Components | shadcn/ui pattern | Copy-paste components we own and can customize. No opaque UI library dependencies. | + +## Backend & Data + +| Layer | Choice | Rationale | +|---|---|---| +| Database | PostgreSQL | Proven, feature-rich, great ORM support. Our relational data model fits it well. | +| ORM | Prisma | Type-safe queries, excellent migration tooling, good DX. | +| Auth | NextAuth.js | Battle-tested, supports many providers, integrates cleanly with Next.js. | +| Storage | Cloudflare R2 | S3-compatible, zero egress fees, good for file uploads and static assets. | +| Payments | TBD | Will evaluate when we have a revenue model. | + +## Tooling + +| Layer | Choice | Rationale | +|---|---|---| +| Package Manager | pnpm | Fast, disk-space efficient, strict `node_modules` layout avoids phantom dependencies. | +| Monorepo | Turborepo (when needed) | Caching and task orchestration. Only adopt when we have >1 app or shared package. | +| CI/CD | GitHub Actions | Native GitHub integration, free for public repos, cheap for private. | +| Lint | ESLint + Prettier | Standard, autofixable, low-friction. | + +## Principles + +- **Server Components by default.** Reach for `"use client"` only when the component actually needs state, effects, or browser APIs. +- **Pure logic in `lib/`, I/O in `services/`.** Business logic does not import from `next/server` or call `fetch` directly. +- **Store money as integers.** MNT (Mongolian Tugrik) in smallest unit. Format on display. +- **Observability before optimization.** Measure before fixing. No tuning without metrics. +- **Idempotency.** Operations should be safe to retry. Infrastructure changes should be reproducible. + +## Open Decisions + +| Decision | Status | Owner | Blocker | +|---|---|---|---| +| Hosting provider (Vercel, Fly, AWS?) | Open | CTO | Need product requirements and traffic estimates | +| Monitoring / alerting stack | Open | CTO | Need hosting decision | +| CDN / edge strategy | Open | CTO | Need hosting decision |