<div align="center">

<!-- DEPLOYMENT COMMAND -->
<div style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); padding: 20px; border-radius: 10px; margin-bottom: 30px;">
  <h3 style="color: white; margin: 0;">STARTER COMMAND</h3>
  <code style="color: #ffd700; font-size: 16px; font-weight: bold;">./scripts/bootstrap-template.sh</code>
</div>

<a id="readme-top"></a>

<!-- PROJECT SHIELDS -->
[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![LinkedIn][linkedin-shield]][linkedin-url]

<!-- PROJECT LOGO -->
<br />
<div align="center">
  <a href="https://git.biohazardvfx.com/nicholai/template">
    <img src="public/template-logo.png" alt="Template Logo" width="400">
  </a>

  <h1 align="center" style="font-size: 48px; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); -webkit-background-clip: text; -webkit-text-fill-color: transparent;">Development Project Template</h1>

  <p align="center" style="font-size: 18px; max-width: 680px;">
    Opinionated starter kit for new projects deployed through my self-hosted Gitea.<br />
    <strong>Documentation-first • Edge-case aware • Automation ready</strong>
    <br />
    <br />
    <a href="#getting-started"><strong>Quick Start »</strong></a>
    ·
    <a href="https://git.biohazardvfx.com/nicholai/template/issues/new?labels=enhancement">Suggest Improvement</a>
  </p>
</div>

---

<!-- TABLE OF CONTENTS -->
<details open>
  <summary><h2>Table of Contents</h2></summary>
  <ol>
    <li><a href="#about-the-template">About The Template</a>
      <ul>
        <li><a href="#why-this-exists">Why This Exists</a></li>
        <li><a href="#core-principles">Core Principles</a></li>
      </ul>
    </li>
    <li><a href="#tech-stack">Tech Stack</a></li>
    <li><a href="#architecture">Architecture</a></li>
    <li><a href="#getting-started">Getting Started</a>
      <ul>
        <li><a href="#prerequisites">Prerequisites</a></li>
        <li><a href="#installation">Installation</a></li>
        <li><a href="#environment-variables">Environment Variables</a></li>
      </ul>
    </li>
    <li><a href="#development">Development</a>
      <ul>
        <li><a href="#common-commands">Common Commands</a></li>
        <li><a href="#docs--checklists">Docs & Checklists</a></li>
      </ul>
    </li>
    <li><a href="#edge-cases">Edge Cases</a></li>
    <li><a href="#testing">Testing</a></li>
    <li><a href="#contributing">Contributing</a></li>
    <li><a href="#license">License</a></li>
    <li><a href="#contact">Contact</a></li>
  </ol>
</details>

---

</div>

## About The Template

<div align="center">
  <img src="public/template-dashboard.png" alt="Template Dashboard Mock" width="800" style="border-radius: 10px; box-shadow: 0 10px 30px rgba(0,0,0,0.3);">
</div>

<br />

This repository is the baseline I use when starting a new product or service. It keeps the process consistent, reduces the time spent wiring boilerplate, and reminds me to account for the edge cases that usually appear late in a project.

### Why This Exists

- **Primed documentation:** Every project starts with a README, stack decision log, bootstrapping checklist, and edge-case catalogue.
- **Automation on day one:** `scripts/` holds helpers to rename the project, configure remotes, and clean example assets.
- **Testing blueprints:** Example Vitest suites (`__tests__/`) demonstrate how to structure API, component, flag, hook, and library tests.
- **Gitea ready:** Pull request templates, Conventional Commit guidance, and workflows match my self-hosted setup.

### Core Principles

| Principle | What it means |
| --- | --- |
| Documentation-first | Write down intent and constraints before diving into code. |
| Edge-case aware | Capture the failure scenarios that repeatedly cause incidents. |
| Reproducible setup | Every project can be re-created from scratch via scripts and docs. |
| Automation ready | Scripts and CI pipelines are easy to adapt or extend. |

<p align="right"><a href="#readme-top">back to top ↑</a></p>

## Tech Stack

- **Framework**: Next.js + TypeScript (adjust as needed)
- **Testing**: Vitest + Testing Library
- **Styling**: Tailwind CSS or CSS Modules (pick one per project)
- **Database**: PostgreSQL (Supabase/Neon friendly)
- **Storage**: S3-compatible providers (AWS S3, Cloudflare R2)
- **Auth**: NextAuth.js or custom token flows
- **Deployment**: Wrangler + Cloudflare Pages/Workers (swap for your platform)

Document any deviations in `docs/stack-decisions.md`.

<p align="right"><a href="#readme-top">back to top ↑</a></p>

## Architecture

```mermaid
flowchart TD
  A[Client] -->|HTTP| B[Next.js App]
  B -->|API Routes| C[(PostgreSQL)]
  B -->|Edge Functions| D[Cloudflare Workers]
  B -->|Auth| E[Identity Provider]
  B -->|Storage SDK| F[(S3/R2 Bucket)]
  D -->|Feature Flags| G[Config Service]
```

- Keep infrastructure definitions under `infra/` once you create them.
- Capture architectural decisions and trade-offs in `docs/stack-decisions.md`.

<p align="right"><a href="#readme-top">back to top ↑</a></p>

## Getting Started

### Prerequisites

- Node.js 20+
- pnpm (preferred) or your package manager of choice
- `jq` (optional, used by bootstrap script)
- Git & access to your Gitea instance

### Installation

1. **Clone / duplicate the template**
   ```bash
   git clone git@git.biohazardvfx.com:nicholai/template.git my-new-project
   cd my-new-project
   ```
2. **Bootstrap**
   ```bash
   ./scripts/bootstrap-template.sh
   ```
3. **Install dependencies**
   ```bash
   pnpm install
   ```
4. **Follow the checklist**
   - Open `docs/bootstrapping.md` and complete each item.

### Environment Variables

Copy `.env.example` to `.env` and fill only the sections you need. The file is structured by concern (database, auth, storage, observability) so you can strip unused parts.

<p align="right"><a href="#readme-top">back to top ↑</a></p>

## Development

### Common Commands

| Command | Description |
| --- | --- |
| `pnpm dev` | Start the Next.js dev server. |
| `pnpm lint` | Run ESLint / formatting checks. |
| `pnpm test` | Execute the Vitest suites. |
| `pnpm build` | Generate a production build. |

### Docs & Checklists

- `docs/bootstrapping.md` — tasks to run through when spinning up a new project.
- `docs/edge-cases.md` — prompts for the weird scenarios that usually break things.
- `docs/stack-decisions.md` — record “why” for each notable tech choice.
- `docs/testing-blueprints.md` — guidance for adapting the example tests.

<p align="right"><a href="#readme-top">back to top ↑</a></p>

## Edge Cases

Edge-case awareness is built into the template:

- Feature flags default to safe behaviour when providers fail.
- Auth, storage, scheduling, and third-party integrations each have dedicated prompts.
- The example tests in `__tests__/flags/` and `__tests__/lib/` show how to assert defensive behaviour.

Add new lessons learned back into `docs/edge-cases.md` so the template evolves with every incident.

<p align="right"><a href="#readme-top">back to top ↑</a></p>

## Testing

- Tests are organised by domain: `api/`, `components/`, `hooks/`, `flags/`, `lib/`.
- Each suite mocks external dependencies and asserts on both happy-path and failure scenarios.
- See `docs/testing-blueprints.md` for tips on customising them to your project.

<p align="right"><a href="#readme-top">back to top ↑</a></p>

## Contributing

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for branching conventions, commit style, and review expectations.

<p align="right"><a href="#readme-top">back to top ↑</a></p>

## License

Use, remix, or extract any portion of this template for your own projects. Attribution is appreciated but not required.

<p align="right"><a href="#readme-top">back to top ↑</a></p>

## Contact

Nicholai — [@biohazardvfx](https://linkedin.com/in/biohazardvfx) — nicholai@biohazardvfx.com

Project Link: [https://git.biohazardvfx.com/nicholai/template-repo](https://git.biohazardvfx.com/nicholai/template-repo)

<p align="right"><a href="#readme-top">back to top ↑</a></p>

<!-- MARKDOWN LINKS & IMAGES -->
<!-- shields -->
[contributors-shield]: https://img.shields.io/gitea/contributors/nicholai/template?style=for-the-badge
[contributors-url]: https://git.biohazardvfx.com/nicholai/template/graphs/contributors
[forks-shield]: https://img.shields.io/gitea/forks/nicholai/template?style=for-the-badge
[forks-url]: https://git.biohazardvfx.com/nicholai/template/network/members
[stars-shield]: https://img.shields.io/gitea/stars/nicholai/template?style=for-the-badge
[stars-url]: https://git.biohazardvfx.com/nicholai/template/stars
[issues-shield]: https://img.shields.io/gitea/issues/nicholai/template?style=for-the-badge
[issues-url]: https://git.biohazardvfx.com/nicholai/template/issues
[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
[linkedin-url]: https://linkedin.com/in/biohazardvfx
