Oss Documentation System

# Project Name

Brief, compelling one-liner explaining what this project does.

[![CI](badge-url)](link) [![License](badge-url)](link)

## What is Project Name?

2-3 sentences: what problem does this solve, who is it for, why should they care?

## Features

- **Feature A**: Brief benefit-oriented description
- **Feature B**: Brief benefit-oriented description

## Quick Start

### Installation

```shell
add the package dependency project-name

import { Project } from 'project-name';
const result = Project.doThing({ input: 'example' });
// Expected output: { status: 'success', data: '...' }

### README Quality Checklist

- [ ] Project name and description clear within 5 seconds
- [ ] Installation takes fewer than 3 steps
- [ ] Working code example is copy-pasteable with expected output
- [ ] All badges are functional and current
- [ ] Links to deeper documentation work
- [ ] License is stated, contributing path is clear

## CONTRIBUTING.md Template

```markdown
# Contributing to [Project]

## Development Setup

### Prerequisites
- Node.js >= 18
- Git

### Local Setup

```shell
git clone [GitHub repository]
cd project
add the package dependency
npm test        # Verify setup
npm run dev     # Start development mode

## Architecture Documentation

### Architecture Decision Record (ADR) Format

```markdown
# ADR-001: Use PostgreSQL for Primary Data Store

## Status
Accepted (2025-01-15)

## Context
We need a primary data store supporting complex queries with joins,
ACID transactions, JSON document storage, and horizontal read scaling.

## Decision
We will use PostgreSQL as the primary data store.

## Rationale
- Mature, well-tested, widely understood
- jsonb covers flexible schema needs
- Read replicas provide sufficient read scaling
- Team has existing expertise

## Alternatives Considered
- **MongoDB**: Flexible schema but weaker transaction support
- **MySQL**: Widely used but weaker JSON support

## Consequences
- Need connection pooling (pgBouncer) for high concurrency
- Migration tooling must support PostgreSQL dialects

## Review Date
2025-07-15 (6 months after adoption)

# Architecture Overview

## System Context

[External Users] → [CDN] → [Web App]
                              ↓
                         [API Gateway]
                         /    |    \
                    [Auth] [Core] [Search]
                      ↓      ↓      ↓
                   [DB]   [DB]  [Search Index]

## Component Descriptions
- **API Gateway**: Request routing, rate limiting, authentication
- **Core Service**: Business logic and data management

## Data Flow: Request Lifecycle
1. Client sends request to CDN/load balancer
2. Gateway validates authentication token
3. Request routed to appropriate service
4. Service processes request and queries database
5. Response returned through the same path

## Key Design Decisions
| Decision | ADR | Date | Status |
|----------|-----|------|--------|
| Primary database | ADR-001 | 2025-01 | Accepted |
| Authentication | ADR-002 | 2025-01 | Accepted |
| API versioning | ADR-003 | 2025-02 | Accepted |

docs/
  index.md
  getting-started/
    installation.md
    quick-start.md
    configuration.md
  guides/
    basic-usage.md
    advanced-features.md
    troubleshooting.md
  api/
    overview.md
    endpoints.md
  architecture/
    overview.md
    adrs/
      001-database.md
      002-authentication.md
  contributing/
    setup.md
    guidelines.md
    releasing.md
  mkdocs.yml

# GitHub Actions: Build and deploy docs
name: Documentation
on:
  push:
    branches: [main]
    paths: ['docs/**', 'mkdocs.yml']
  pull_request:
    paths: ['docs/**', 'mkdocs.yml']

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: install the package via pip mkdocs-material
      - run: mkdocs build --strict

  deploy:
    if: github.ref == 'refs/heads/main'
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: install the package via pip mkdocs-material
      - run: mkdocs gh-deploy --force

# .markdownlint.yml
default: true
MD013:
  line_length: 120
  code_blocks: false
  tables: false
MD033: false  # Allow inline HTML for badges
MD041: false  # First line heading (frontmatter)

# Documentation PR check
name: Docs Lint
on: [pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: DavidAnson/markdownlint-cli2-action@v16
        with:
          globs: '**/*.md'
      - uses: streetsidesoftware/cspell-action@v6
        with:
          files: '**/*.md'
      - uses: lycheeverse/lychee-action@v1
        with:
          args: '--no-progress docs/**/*.md README.md'

                Practical
                   │
     Tutorials     │    How-To Guides
     (Learning)    │    (Problem-solving)
                   │
Studying ──────────┼──────────── Working
                   │
     Explanation   │    Reference
     (Understanding)│   (Information)
                   │
               Theoretical