Initial commit

Author: ozturkberkay

.act.secrets.example

@@ -0,0 +1,2 @@
+GITHUB_TOKEN=
+CLOUDFLARE_API_TOKEN=

.actrc

@@ -0,0 +1,4 @@
+--container-architecture linux/amd64
+-P ubuntu-slim=ghcr.io/catthehacker/ubuntu:act-24.04
+-P ubuntu-24.04-arm=ghcr.io/catthehacker/ubuntu:act-24.04
+-P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-24.04

.agents/skills/code-review/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: code-review
+description: You **MUST** use this after the implementation changes are validated and ready for review.
+---
+
+**CRITICAL:** **Must** be executed by the `code-reviewer` subagent.
+
+You **must** follow the steps below:
+
+1. Review the code very carefully and look for issues without nit-picking.
+2. Ensure the changes follow existing coding practices and directory structures.
+3. Ensure perfect unit and integration test coverage for all possible scenarios.
+4. Ensure no security risks are introduced.
+5. Ensure no performance bottlenecks are introduced.
+6. Ensure no unnecessary code complexity is introduced.

.agents/skills/design-doc/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: design-doc
+description: You **MUST** use this before implementing any new feature or making significant changes to the codebase. Not needed for small refactors, bug fixes, or minor tweaks.
+---
+
+Should be executed by the `design-lead` subagent.
+
+You **must** follow the steps below:
+
+1. Always start by reading the original product brief
+   `docs/brief/2026_01_31_tokenoverflow.md` and @README.md
+2. If provided, read the PRD carefully to understand the requirements.
+3. Run `source scripts/src/includes.sh` and
+   `create_doc design <feature_name>` to create the design document.
+4. Find your design document under `docs/design/`.
+5. Read the template and understand the structure.
+6. Ask clarifying questions if you are not sure about anything.
+7. Before starting the design, identify what research you need to do and use
+   subagents to do deep research online.
+8. Fill the design document section by section.
+9. Always provide multiple alternatives with clearly defined trade-offs in a
+   table format. Also give examples of what they would look like in practice.
+10. After each section, ask for approval before moving to the next one.
+11. Make sure all PRD requirements are satisfied.
+12. Once done, ask for a review and keep repeating until you get approval.
+
+List of guidelines you **must** follow:
+
+- Prevent scope creep by sticking to the original requirements.
+- Never try to re-invent the wheel. Research best practices using subagents.
+- When introducing new libraries, always check if they are well-maintained.
+- When iterating, do not mention the changes made to previous iterations.
+- Ensure every design follows industry best practices without taking any
+  shortcuts, or reaching for hacks.
+- Ensure the design respects the current architecture and coding standards of
+  the codebase.
+- Use the latest version of dependencies unless there is a strong reason not to.
+- Do not edit historical design documents.
+
+**CRITICAL:** Your work is not complete until you fully fill the design document
+on disk and save your changes. Do not leave an empty template.

.agents/skills/implement-design/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: implement-design
+description: You **must** use this when implementing the code for an approved design document.
+---
+
+**Must** be executed by the `engineer` subagent.
+
+You are required to follow these guidelines:
+
+- Stick to the approved design document requirements. Do **not** deviate.
+- Every line of code is a liability and **must** be justified.
+- You **must** always use TDD. Have a failing test first before writing code!
+- You **must** use three-tier test architecture:
+    - `unit/`: Pure business logic tests with zero external dependencies
+    - `integration/`: In-process integration tests with external dependencies
+    - `e2e/`: Black-box testing of the whole system based on user stories
+- Never mix test with source code.
+- Test directories should mirror the structure of the source code directories.
+- You **must** never use shortcuts/hacks just to get your current task working.
+- Avoid writing single big files; prefer splitting into multiple.
+- Follow FCIS architectural pattern when implementing services:
+    - Functional core: Unit testable business logic
+    - Imperative shell: External dependencies like I/O, use integration tests
+- Always finish your work by using the `validate-changes` skill.
+- **NEVER** change the code coverage threshold!
+- Comment the why, not the what.
+- Do not introduce code duplication.
+
+Once you're done, if asked to commit your changes. Otherwise, you should run:
+
+```shell
+git add --all
+prek run
+```
+
+**CRITICAL:** Your work is not done until every single pre-commit hook passes!
+E2E tests require full docker environment running, DON'T skip it!

.agents/skills/postgres/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: postgres
+description: PostgreSQL best practices, query optimization, connection troubleshooting, and performance improvement. Load when working with Postgres databases.
+license: MIT
+metadata:
+    author: planetscale
+    version: "1.0.0"
+---
+
+# Postgres
+
+| Topic                  | Reference                                                                      | Use for                                                      |
+|------------------------|--------------------------------------------------------------------------------|--------------------------------------------------------------|
+| Schema Design          | [references/schema-design.md](./references/schema-design.md)                   | Tables, primary keys, data types, foreign keys               |
+| Indexing               | [references/indexing.md](./references/indexing.md)                             | Index types, composite indexes, performance                  |
+| Index Optimization     | [references/index-optimization.md](./references/index-optimization.md)         | Unused/duplicate index queries, index audit                  |
+| Partitioning           | [references/partitioning.md](./references/partitioning.md)                     | Large tables, time-series, data retention                    |
+| Query Patterns         | [references/query-patterns.md](./references/query-patterns.md)                 | SQL anti-patterns, JOINs, pagination, batch queries          |
+| Optimization Checklist | [references/optimization-checklist.md](./references/optimization-checklist.md) | Pre-optimization audit, cleanup, readiness checks            |
+| MVCC and VACUUM        | [references/mvcc-vacuum.md](./references/mvcc-vacuum.md)                       | Dead tuples, long transactions, xid wraparound prevention    |
+| Process Architecture   | [references/process-architecture.md](./references/process-architecture.md)     | Multi-process model, connection pooling, auxiliary processes |
+| Memory Architecture    | [references/memory-management-ops.md](./references/memory-management-ops.md)   | Shared/private memory layout, OS page cache, OOM prevention  |
+| MVCC Transactions      | [references/mvcc-transactions.md](./references/mvcc-transactions.md)           | Isolation levels, XID wraparound, serialization errors       |
+| WAL and Checkpoints    | [references/wal-operations.md](./references/wal-operations.md)                 | WAL internals, checkpoint tuning, durability, crash recovery |
+| Replication            | [references/replication.md](./references/replication.md)                       | Streaming replication, slots, sync commit, failover          |
+| Storage Layout         | [references/storage-layout.md](./references/storage-layout.md)                 | PGDATA structure, TOAST, fillfactor, tablespaces, disk mgmt  |
+| Monitoring             | [references/monitoring.md](./references/monitoring.md)                         | pg_stat views, logging, pg_stat_statements, host metrics     |
+| Backup and Recovery    | [references/backup-recovery.md](./references/backup-recovery.md)               | pg_dump, pg_basebackup, PITR, WAL archiving, backup tools    |

.agents/skills/postgres/references/backup-recovery.md

@@ -0,0 +1,41 @@
+---
+title: Backup and Recovery
+description: Logical/physical backups, PITR, WAL archiving, backup tools, and recovery strategies
+tags: postgres, backup, recovery, pitr, pg_dump, pg_basebackup, wal-archiving, operations
+---
+
+# Backup and Recovery
+
+**FUNDAMENTAL RULE: Backups are useless until you've successfully tested recovery.**
+
+## Logical Backups (pg_dump)
+Exports as SQL or custom format; portable across PG versions and architectures. Formats: `-Fp` (plain SQL), `-Fc` (custom compressed, selective restore), `-Fd` (directory, parallel with `-j`), `-Ft` (tar, avoid). Use `-Fd -j 4` for large DBs. Restore: `pg_restore -d dbname file.dump`; add `-j` for parallel restore. Selective table restore: `pg_restore -t tablename`. Slow for large DBs; RPO = backup frequency (typically 24h).
+
+## Physical Backups (pg_basebackup)
+Copies raw PGDATA; same major version and platform required; cross-architecture works if same endianness (e.g., x86_64 ↔ ARM64). Faster for large clusters; includes all databases. Flags: `-Ft -z -P` for compressed tar with progress. Manual alternative: `pg_backup_start()` → copy PGDATA → `pg_backup_stop()` (complex; must write returned `backup_label`).
+
+## PITR (Point-in-Time Recovery)
+Requires base backup + continuous WAL archiving. Restores to any timestamp, transaction, or named restore point. Without PITR: restore only to backup time (potentially lose hours). With PITR: RPO = minutes. `archive_command` must return 0 ONLY when file is safely stored—premature 0 = data loss risk. `wal_level` must be `replica` or `logical` (not `minimal`).
+
+## WAL Archiving
+`archive_mode=on`, `archive_command='test ! -f /archive/%f && cp %p /archive/%f'`. **Test archive command as postgres user** (not root) since permission issues are common. Monitor `pg_stat_archiver` for `failed_count`, `last_archived_time`. Archive failures prevent WAL recycling → disk fills.
+
+## Tool Comparison
+| Tool | Use case |
+|------|----------|
+| pg_dump | Small DBs, migrations, selective restore |
+| pg_basebackup | Basic PITR, built-in |
+| pgBackRest | Production—parallel, incremental, S3/GCS/Azure, retention |
+| Barman | Enterprise PITR, retention policies |
+| WAL-G | Cloud-native, S3/GCS/Azure |
+
+## RPO/RTO
+Logical only: RPO = backup interval (hours); RTO = hours. PITR: RPO = minutes; RTO = hours. Synchronous replication: RPO = 0; RTO = seconds to minutes (failover).
+
+## Operational Rules
+- Verify integrity with `pg_verifybackup` (PG 13+)
+- Test recovery / PITR regularly
+- Take backups from standby to avoid impacting primary
+- Retention: 7 daily, 4 weekly, 12 monthly
+- Monitor archive growth and backup age
+- **Never assume backups work without testing**

.agents/skills/postgres/references/index-optimization.md

@@ -0,0 +1,69 @@
+---
+title: Index Optimization Queries
+description: Index audit queries
+tags: postgres, indexes, unused-indexes, duplicate-indexes, optimization
+---
+
+# Index Optimization
+
+## Identify Unused Indexes
+
+Query to find unused indexes:
+
+```sql
+-- indexes with 0 scans (check pg_stat_reset / pg_postmaster_start_time first)
+SELECT
+   s.schemaname,
+   s.relname AS table_name,
+   s.indexrelname AS index_name,
+   pg_size_pretty(pg_relation_size(s.indexrelid)) AS index_size
+ FROM pg_catalog.pg_stat_user_indexes s
+ JOIN pg_catalog.pg_index i ON s.indexrelid = i.indexrelid
+ WHERE s.idx_scan = 0
+   AND 0 <> ALL (i.indkey)       -- exclude expression indexes
+   AND NOT i.indisunique          -- exclude UNIQUE indexes
+   AND NOT EXISTS (               -- exclude constraint-backing indexes
+     SELECT 1 FROM pg_catalog.pg_constraint c
+     WHERE c.conindid = s.indexrelid
+   )
+ ORDER BY pg_relation_size(s.indexrelid) DESC;
+```
+
+## Indexes Per Table Guidelines
+
+- **< 5**: Normal
+- **5-10**: Monitor (Verify necessity)
+- **> 10**: Audit required (High write overhead)
+
+```sql
+SELECT relname AS table, count(*) as index_count
+FROM pg_stat_user_indexes
+GROUP BY relname
+ORDER BY count(*) DESC;
+```
+
+## Identify Unused Indexes
+
+Indexes with identical definitions (after normalizing names) on the same table are duplicates:
+
+```sql
+SELECT
+  schemaname || '.' || tablename AS table,
+  array_agg(indexname) AS duplicate_indexes,
+  pg_size_pretty(sum(pg_relation_size((schemaname || '.' || indexname)::regclass))) AS total_size
+FROM pg_indexes
+WHERE schemaname NOT IN ('pg_catalog', 'information_schema')
+GROUP BY schemaname, tablename,
+  regexp_replace(indexdef, 'INDEX \S+ ON ', 'INDEX ON ')
+HAVING count(*) > 1;
+```
+
+**Always confirm with a human before dropping or removing any indexes identified by the queries above.** Even indexes with 0 scans may be needed for infrequent but critical queries, and stats may have been reset recently.
+
+## Per-table Index Count Guidelines
+
+| Index Count | Recommendation                              |
+| ----------- | ------------------------------------------- |
+| <5          | Normal                                      |
+| 5-10        | Review for unused/duplicates                |
+| >10         | Audit required - significant write overhead |

.agents/skills/postgres/references/indexing.md

@@ -0,0 +1,61 @@
+---
+title: Indexing Best Practices
+description: Index design guide
+tags: postgres, indexes, composite, partial, covering, gin, brin
+---
+
+# Indexing Best Practices
+
+## Core Rules
+
+1. **Always index foreign key columns** — PostgreSQL does not auto-create these
+2. **Index columns in WHERE, JOIN, and ORDER BY** clauses
+3. **Don't over-index** — each index slows writes and uses storage
+4. **Verify with EXPLAIN ANALYZE** — confirm indexes are actually used
+
+## Composite Indexes
+
+Put equality columns first, then range/sort columns:
+
+```sql
+-- WHERE status = 'active' AND created_at > '2026-01-01'
+CREATE INDEX order_status_created_idx ON order (status, created_at);
+```
+
+A composite index on `(a, b)` supports queries on `a` + `b` and `a` alone, but not `b` alone.
+
+## Partial Indexes
+
+Reduce index size by filtering to common query patterns.
+Only use if index size is problematic but the index is needed for performance.
+
+```sql
+CREATE INDEX order_active_idx ON order (customer_id)
+  WHERE status = 'active';
+```
+
+## Covering Indexes
+
+Consider creating covering indexes for commonly executed query patterns that return only 1 or a small number of columns.
+
+## Index Types
+
+| Type | Use Case | Example |
+| --- | --- | --- |
+| B-tree (default) | Equality, range, sorting | `WHERE id = 1`, `ORDER BY date` |
+| GIN | Arrays, JSONB, full-text | `WHERE tags @> ARRAY['x']` |
+| GiST | Geometric, range types, full-text | PostGIS, `tsrange`, `tsvector` |
+| BRIN | Large sequential/time-series | Append-only logs, events (requires physical row order correlation) |
+
+```sql
+CREATE INDEX metadata_idx ON order USING GIN (metadata);       -- JSONB
+CREATE INDEX event_created_idx ON event USING BRIN (created_at); -- time-series
+```
+
+## Guidelines
+
+- Name indexes consistently: `{table}_{column}_idx`
+- Review for unused indexes periodically
+- **Always confirm with a human before removing or dropping any indexes** — even unused ones may serve a purpose not reflected in recent stats
+- Use partial indexes for frequently filtered subsets
+- Use covering indexes on hot read paths

.agents/skills/postgres/references/memory-management-ops.md

@@ -0,0 +1,39 @@
+---
+title: Memory Architecture and OOM Prevention
+description: PostgreSQL shared/private memory layout, OS page cache interaction, and OOM avoidance strategies
+tags: postgres, memory, shared_buffers, work_mem, oom, architecture, operations
+---
+
+# Memory Architecture and OOM Prevention
+
+## Memory Areas
+
+- **Shared memory**: `shared_buffers` — main data cache, all processes, requires restart to change.
+- **Private per backend**: `work_mem` (sorts/hashes/joins, per-operation); `maintenance_work_mem` (VACUUM, CREATE INDEX, ALTER TABLE ADD FOREIGN KEY); `temp_buffers` (8MB default).
+- **Planner hint only**: `effective_cache_size` is NOT allocated — set to ~50–75% of total RAM.
+- **Hash multiplier**: `hash_mem_multiplier` (default 2.0) means hash ops use up to 2× `work_mem`.
+
+## Memory Multiplication Danger
+
+Maximum potential: `work_mem × operations_per_query × (parallel_workers + 1) × connections` (leader participates by default via `parallel_leader_participation = on`; hash operations use up to `hash_mem_multiplier × work_mem`, default 2.0). Example: 128MB work_mem, 3 ops (2 sorts + 1 hash join), 2 parallel workers, 100 connections → 2 sorts at 128MB = 256MB, 1 hash join at 128MB × 2.0 = 256MB, per process = 512MB, × 3 processes (2 workers + leader) = 1536MB/query, × 100 connections = **~150GB** worst case. This case is rare.
+Not all queries hit limits at once, but high concurrency + large datasets approach it. This is a common cause of OOM in containerized/Kubernetes deployments. Plan capacity with a 1.5–2× safety margin.
+
+## OS Page Cache (Double Buffering)
+
+Data exists in both `shared_buffers` and OS page cache. A miss in shared_buffers can still hit OS cache (avoiding disk I/O). Extremely large shared_buffers can hurt performance: less OS cache, slower startup, heavier checkpoints. Optimal split depends on workload (OLTP vs OLAP).
+
+## OOM Prevention
+
+- Implement connection pooling to reduce total backend count.
+- Reduce `work_mem` globally; use per-session overrides for heavy queries only.
+- Lower `max_parallel_workers_per_gather` in high-concurrency systems.
+- Set `statement_timeout` to kill runaway queries.
+- Monitor: `dmesg -T | grep "killed process"` and `temp_blks_written` in pg_stat_statements.
+
+## Operational Rules
+
+- Tune per-session first, global last.
+- Suspect OOM when memory spikes during high concurrency, dashboards, or large batch jobs.
+- Increase memory only after confirming spill behavior (`temp_blks_written > 0`).
+- `maintenance_work_mem` can be set much higher (1–2GB) — fewer processes use it. Cap autovacuum with `autovacuum_work_mem` to avoid `autovacuum_max_workers × maintenance_work_mem` memory spikes.
+- `shared_buffers` change requires full restart; `work_mem` is per-session changeable.