# Architecture Decision Records - {{titleCase FEATURE_NAME}}

## ADR-001: {Decision Title}

**Date:** {{DATE}}
**Status:** Proposed | Accepted | Deprecated | Superseded
**Deciders:** MORPH Agents, Developer

### Context

{Describe the context and problem that led to this decision}

### Decision

{Describe the decision made}

### Consequences

**Pros:**
- {Positive consequence 1}
- {Positive consequence 2}

**Cons:**
- {Negative consequence 1}

**Risks:**
- {Identified risk}

### Alternatives Considered

#### Option A: {Name}
- Pros: {advantages}
- Cons: {disadvantages}
- **Rejected because:** {reason}

#### Option B: {Name}
- Pros: {advantages}
- Cons: {disadvantages}
- **Rejected because:** {reason}

---

{{#if (eq STACK "nextjs-neon")}}
## ADR-002: Database Access Strategy

**Date:** {{DATE}}
**Status:** Accepted

### Context

Need to decide how the .NET API accesses Neon PostgreSQL.

### Decision

Use Dapper with Npgsql for direct SQL queries. No EF Core.

### Consequences

**Pros:**
- Full control over SQL queries
- Better performance (no ORM overhead)
- Direct access to PostgreSQL features (jsonb, pgvector, functions)
- RLS policies apply naturally through connection

**Cons:**
- No automatic migrations (use Neon CLI / dotnet ef instead)
- Manual SQL query writing
- No change tracking

---

## ADR-003: Auth Strategy

**Date:** {{DATE}}
**Status:** Accepted

### Context

Need authentication for both Next.js frontend and .NET API.

### Decision

Use Neon Auth (Better Auth) for authentication. Auth data lives in the Neon database. JWT validated by .NET API middleware.

### Consequences

**Pros:**
- Auth data in same database — no external provider, no sync delays
- RLS policies work with Neon Auth JWT via auth.user_id() / pg_session_jwt
- Built-in social login, email/password via @neondatabase/auth SDK
- Branch isolation — each Neon branch gets isolated auth data
- No webhooks needed — query neon_auth schema directly

**Cons:**
- Neon Auth is currently in Beta
- JWT must be forwarded to .NET API for backend auth
{{/if}}

---

## Template for New ADRs

```markdown
## ADR-XXX: {Title}

**Date:**
**Status:** Proposed | Accepted | Deprecated | Superseded

### Context
{Why is this decision needed?}

### Decision
{What was decided?}

### Consequences
**Pros:** {list}
**Cons:** {list}
```

---

*Generated by MORPH Framework*