proagents 1.0.0

package/proagents/adr/examples/api-versioning.md

@@ -0,0 +1,297 @@
+# ADR-0002: Use URL-Based API Versioning
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **Status** | Accepted |
+| **Date** | 2024-01-20 |
+| **Author** | @api-lead |
+| **Reviewers** | @tech-lead, @frontend-lead, @mobile-lead |
+| **Tags** | api, versioning, backend |
+
+---
+
+## Context
+
+Our API is evolving rapidly, and we need to make breaking changes to improve the data model and fix design mistakes. However, we have multiple clients:
+
+- Web application (controlled release cycle)
+- iOS app (App Store review delays)
+- Android app (Play Store delays)
+- Third-party integrations (no control over update timeline)
+
+We need a versioning strategy that allows us to:
+- Make breaking changes without disrupting existing clients
+- Maintain multiple versions during transition periods
+- Deprecate old versions gracefully
+- Keep the implementation manageable
+
+Currently, our API has no versioning, and breaking changes require coordinated releases across all clients, which is becoming increasingly difficult.
+
+---
+
+## Decision
+
+We will implement **URL-based API versioning** with the following structure:
+
+```
+https://api.example.com/v1/users
+https://api.example.com/v2/users
+```
+
+**Rules:**
+- Major version in URL path (`/v1/`, `/v2/`, etc.)
+- Minor/patch changes within a version are backward compatible
+- Support N-2 versions minimum (e.g., v3 current, v2 and v1 still supported)
+- Deprecation period of 6 months before version removal
+- Version-specific documentation and changelogs
+
+---
+
+## Rationale
+
+URL-based versioning was chosen because:
+
+1. **Visibility**: Version is immediately apparent in logs, monitoring, and debugging.
+
+2. **Simplicity**: No header parsing required; easy to test with browser or curl.
+
+3. **Routing**: Easy to route different versions to different server instances if needed.
+
+4. **Caching**: CDN and proxy caching works naturally without custom rules.
+
+5. **Documentation**: API docs can cleanly separate versions.
+
+6. **Adoption**: Most widely used pattern, familiar to developers.
+
+---
+
+## Consequences
+
+### Positive
+
+- **Clear separation** between API versions
+- **Easy debugging** - version visible in all requests
+- **Simple client implementation** - just change base URL
+- **Independent deployment** - can deploy v2 without affecting v1
+- **Gradual migration** - clients can upgrade on their own schedule
+- **Clean deprecation** - can monitor and sunset old versions
+
+### Negative
+
+- **URL pollution** - version becomes part of the resource path
+- **Duplication** - may need to duplicate code for multiple versions
+- **Maintenance burden** - supporting multiple versions increases work
+- **Not pure REST** - version is not a resource characteristic
+
+### Neutral
+
+- Requires documentation for each supported version
+- Need monitoring per version to track adoption
+
+---
+
+## Alternatives Considered
+
+### Alternative 1: Header-Based Versioning
+
+**Description:** Version specified in HTTP header (`Accept: application/vnd.api.v1+json`)
+
+**Pros:**
+- Cleaner URLs
+- More "RESTful"
+- Flexible media type negotiation
+
+**Cons:**
+- Harder to test (can't just use browser)
+- Version not visible in logs without custom parsing
+- Caching requires header inspection
+- More complex client implementation
+
+**Why not chosen:** The debugging and caching complications outweigh the purity benefits.
+
+### Alternative 2: Query Parameter Versioning
+
+**Description:** Version in query string (`/users?version=1`)
+
+**Pros:**
+- URLs stay clean for latest version
+- Easy to implement
+
+**Cons:**
+- Easy to forget parameter
+- Caching complications
+- Looks hacky
+- Conflicts with actual query parameters
+
+**Why not chosen:** Too easy to accidentally use wrong version; feels unprofessional.
+
+### Alternative 3: No Versioning (Evolutionary API)
+
+**Description:** Never make breaking changes; only additive changes.
+
+**Pros:**
+- No version management
+- Single codebase
+- Simple
+
+**Cons:**
+- Limits our ability to improve API design
+- Technical debt accumulates
+- Doesn't work for significant changes
+
+**Why not chosen:** We need the flexibility to make breaking improvements to our API.
+
+### Alternative 4: Date-Based Versioning
+
+**Description:** Use dates in URL (`/2024-01-15/users`)
+
+**Pros:**
+- Clear when version was released
+- Naturally ordered
+
+**Cons:**
+- Verbose URLs
+- Confusing if version released on different dates
+- Not a standard pattern
+
+**Why not chosen:** Non-standard, potentially confusing for developers.
+
+---
+
+## Implementation
+
+### Approach
+
+We will implement versioning as a first-class routing concern with shared code where possible.
+
+### Structure
+
+```
+src/
+├── api/
+│   ├── v1/
+│   │   ├── routes/
+│   │   ├── controllers/
+│   │   └── schemas/
+│   ├── v2/
+│   │   ├── routes/
+│   │   ├── controllers/
+│   │   └── schemas/
+│   └── shared/
+│       ├── middleware/
+│       ├── services/
+│       └── utils/
+```
+
+### Routing
+
+```typescript
+// Server setup
+import v1Router from './api/v1/routes';
+import v2Router from './api/v2/routes';
+
+app.use('/v1', v1Router);
+app.use('/v2', v2Router);
+
+// Default to latest
+app.use('/api', v2Router);
+```
+
+### Version Lifecycle
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   Active    │ →   │  Current    │ →   │ Deprecated  │ →   │   Sunset    │
+│  (default)  │     │             │     │             │     │             │
+└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
+     v2                  v1                  v0               (removed)
+```
+
+### Deprecation Headers
+
+```typescript
+// For deprecated versions
+app.use('/v1', (req, res, next) => {
+  res.set('Deprecation', 'true');
+  res.set('Sunset', 'Sat, 15 Jun 2024 00:00:00 GMT');
+  res.set('Link', '</v2>; rel="successor-version"');
+  next();
+});
+```
+
+### Phases
+
+1. **Phase 1: Infrastructure** (Sprint 1)
+   - Set up versioned routing
+   - Create v1 namespace for existing API
+   - Add version monitoring
+
+2. **Phase 2: Documentation** (Sprint 1)
+   - Version-specific API docs
+   - Migration guide template
+   - Deprecation policy documentation
+
+3. **Phase 3: v2 Development** (Sprint 2-3)
+   - Design v2 schema
+   - Implement v2 endpoints
+   - Create migration guide
+
+4. **Phase 4: Client Migration** (Sprint 4-6)
+   - Update web application
+   - Update mobile applications
+   - Notify third-party integrators
+
+### Risks
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| Clients don't migrate | Medium | High | Clear deprecation timeline, support |
+| Code duplication | High | Medium | Shared services layer |
+| Version proliferation | Low | Medium | Strict version policy, regular cleanup |
+
+---
+
+## Validation
+
+### Success Criteria
+
+- [ ] All existing clients work without changes on /v1
+- [ ] New features can be added to /v2 without breaking /v1
+- [ ] Version-specific monitoring shows clear adoption metrics
+- [ ] Documentation clearly separates version information
+- [ ] At least 80% of traffic on latest version within 6 months
+
+### Metrics to Track
+
+- Request count per version
+- Error rate per version
+- Client distribution per version
+- Time to deprecation compliance
+
+### Review Date
+
+This decision will be reviewed on 2024-07-20 (6 months after implementation) to assess:
+- Is the versioning strategy working?
+- Are we maintaining too many versions?
+- Should we adjust the deprecation timeline?
+
+---
+
+## References
+
+- [API Versioning Best Practices](https://www.postman.com/api-platform/api-versioning/)
+- [Stripe API Versioning](https://stripe.com/docs/api/versioning)
+- [GitHub API Versioning](https://docs.github.com/en/rest/overview/api-versions)
+- Internal RFC: API Design Guidelines (link)
+
+---
+
+## Changelog
+
+| Date | Author | Change |
+|------|--------|--------|
+| 2024-01-18 | @api-lead | Initial draft |
+| 2024-01-19 | @api-lead | Added deprecation headers section |
+| 2024-01-20 | @api-lead | Status changed to Accepted |

package/proagents/adr/examples/database-choice.md

@@ -0,0 +1,264 @@
+# ADR-0001: Use PostgreSQL for Primary Database
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **Status** | Accepted |
+| **Date** | 2024-01-15 |
+| **Author** | @tech-lead |
+| **Reviewers** | @architect, @senior-dev, @dba |
+| **Tags** | database, infrastructure, data |
+
+---
+
+## Context
+
+Our application has grown beyond the capabilities of our current SQLite database. We're experiencing:
+
+- Slow query performance with 10M+ records
+- Limited concurrent connection support
+- No support for advanced features like full-text search
+- Inability to scale horizontally
+
+We need to choose a production-grade database that can:
+- Handle our current scale (10M records, 1000 req/s)
+- Scale to 10x our current load
+- Support complex queries and joins
+- Provide reliability and data integrity
+- Integrate with our Node.js backend
+
+The team has varying experience with different database systems, but most are familiar with SQL-based databases.
+
+---
+
+## Decision
+
+We will migrate from SQLite to **PostgreSQL** as our primary database.
+
+Specifically:
+- Use **Amazon RDS for PostgreSQL** for managed hosting
+- Start with **db.m5.large** instance (2 vCPU, 8 GB RAM)
+- Enable **Multi-AZ** for high availability
+- Use **read replicas** for read-heavy workloads
+- Implement connection pooling with **PgBouncer**
+
+---
+
+## Rationale
+
+PostgreSQL was chosen because:
+
+1. **Performance**: PostgreSQL handles complex queries efficiently with its sophisticated query planner and indexing options.
+
+2. **Scalability**: Supports read replicas, table partitioning, and connection pooling for horizontal scaling.
+
+3. **Features**: Offers JSON support, full-text search, and advanced data types we need.
+
+4. **Reliability**: ACID compliance, proven track record for data integrity.
+
+5. **Ecosystem**: Excellent Node.js support via `pg` and `prisma`, plus tools like pgAdmin.
+
+6. **Team Knowledge**: Two team members have production PostgreSQL experience.
+
+7. **Managed Options**: AWS RDS provides automated backups, patching, and failover.
+
+---
+
+## Consequences
+
+### Positive
+
+- **10x query performance improvement** for complex joins and aggregations
+- **Better concurrency** with MVCC and proper connection pooling
+- **Full-text search** without external dependencies
+- **JSON support** for flexible schema evolution
+- **Automated ops** with RDS (backups, patching, monitoring)
+- **High availability** with Multi-AZ deployment
+
+### Negative
+
+- **Migration effort**: Estimated 2 weeks for data migration and testing
+- **Operational cost**: ~$150/month for RDS vs $0 for SQLite
+- **Complexity increase**: New infrastructure to manage and monitor
+- **Learning curve**: Some team members unfamiliar with PostgreSQL specifics
+
+### Neutral
+
+- SQL syntax is similar, minimal code changes needed
+- Existing ORM (Prisma) supports PostgreSQL
+
+---
+
+## Alternatives Considered
+
+### Alternative 1: MySQL
+
+**Description:** Another popular open-source relational database.
+
+**Pros:**
+- Wide adoption, lots of resources
+- Good performance for simple queries
+- Lower memory footprint
+
+**Cons:**
+- Weaker support for complex queries
+- Less sophisticated query planner
+- Limited JSON functionality
+
+**Why not chosen:** PostgreSQL's superior query optimizer and JSON support better match our needs for complex analytics queries.
+
+### Alternative 2: MongoDB
+
+**Description:** Document-oriented NoSQL database.
+
+**Pros:**
+- Flexible schema
+- Easy horizontal scaling
+- Good for document-heavy workloads
+
+**Cons:**
+- Requires denormalization of our relational data
+- No transactions across documents (until recently)
+- Team has minimal MongoDB experience
+
+**Why not chosen:** Our data model is inherently relational. Migrating to MongoDB would require significant data model changes and team training.
+
+### Alternative 3: Amazon DynamoDB
+
+**Description:** Fully managed NoSQL database service.
+
+**Pros:**
+- Fully managed, zero ops
+- Excellent scaling
+- Pay-per-use pricing
+
+**Cons:**
+- Limited query flexibility
+- No SQL support
+- Complex pricing model
+- Requires complete application rewrite
+
+**Why not chosen:** The query limitations and required application changes make this unsuitable for our use case.
+
+### Alternative 4: Do Nothing (Keep SQLite)
+
+**Description:** Continue using SQLite with optimizations.
+
+**Pros:**
+- No migration effort
+- Zero operational cost
+- Simple deployment
+
+**Cons:**
+- Performance issues will worsen
+- Cannot support concurrent writes well
+- Missing features we need
+
+**Why not chosen:** SQLite cannot meet our current needs, let alone scale for future growth.
+
+---
+
+## Implementation
+
+### Approach
+
+We will perform a phased migration:
+1. Set up PostgreSQL infrastructure
+2. Migrate schema and data
+3. Run both databases in parallel
+4. Validate data consistency
+5. Switch traffic to PostgreSQL
+6. Decommission SQLite
+
+### Phases
+
+1. **Phase 1: Infrastructure Setup** (Week 1)
+   - Provision RDS instance
+   - Set up VPC and security groups
+   - Configure PgBouncer
+   - Set up monitoring
+
+2. **Phase 2: Schema Migration** (Week 1)
+   - Convert SQLite schema to PostgreSQL
+   - Set up Prisma for PostgreSQL
+   - Update connection strings
+   - Test queries locally
+
+3. **Phase 3: Data Migration** (Week 2)
+   - Export data from SQLite
+   - Transform and import to PostgreSQL
+   - Validate data integrity
+   - Set up ongoing sync
+
+4. **Phase 4: Parallel Running** (Week 2)
+   - Write to both databases
+   - Read from PostgreSQL
+   - Monitor for discrepancies
+   - Performance testing
+
+5. **Phase 5: Cutover** (Week 2)
+   - Switch all traffic to PostgreSQL
+   - Monitor closely for 48 hours
+   - Keep SQLite as backup
+
+6. **Phase 6: Cleanup** (Week 3)
+   - Remove SQLite code
+   - Remove dual-write logic
+   - Document new architecture
+
+### Risks
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| Data loss during migration | Low | Critical | Full backups, validation scripts |
+| Performance regression | Medium | High | Load testing before cutover |
+| Extended downtime | Low | High | Parallel running phase |
+| Query compatibility issues | Medium | Medium | Early testing, Prisma abstraction |
+
+---
+
+## Validation
+
+### Success Criteria
+
+- [ ] All queries execute in < 500ms (p99)
+- [ ] Zero data loss verified by row count and checksum comparison
+- [ ] Application handles 2000 req/s in load testing
+- [ ] 99.9% uptime maintained during migration
+- [ ] No increase in application error rate
+
+### Metrics to Track
+
+- Query latency (p50, p95, p99)
+- Connection pool utilization
+- Database CPU and memory usage
+- Replication lag (for read replicas)
+- Application error rate
+
+### Review Date
+
+This decision will be reviewed on 2024-04-15 (3 months after implementation) to assess:
+- Performance improvements achieved
+- Operational burden
+- Any unforeseen issues
+
+---
+
+## References
+
+- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
+- [Amazon RDS for PostgreSQL](https://aws.amazon.com/rds/postgresql/)
+- [Prisma with PostgreSQL](https://www.prisma.io/docs/concepts/database-connectors/postgresql)
+- Internal RFC: Database Evaluation (link)
+- Performance benchmarks (link)
+
+---
+
+## Changelog
+
+| Date | Author | Change |
+|------|--------|--------|
+| 2024-01-10 | @tech-lead | Initial draft |
+| 2024-01-12 | @tech-lead | Updated based on architecture review |
+| 2024-01-15 | @tech-lead | Status changed to Accepted |