OpenComments

OpenComments is a modern, accessible public commenting platform that enables transparent government by making it easy for agencies to collect, moderate, and publish public feedback on policies and proposals.

Project Status

OpenComments is currently transitioning from a hackathon prototype to a production-ready platform.

• Delivery tracking: docs/plan/README.md
• Milestones: docs/plan
• Current focus: release readiness evidence maintenance and operational rollout
• RBAC and account model: docs/RBAC_ACCOUNT_ORG_MANAGEMENT.md

🏛️ Project Purpose

OpenComments bridges the gap between government agencies and citizens by providing a secure, user-friendly platform for public comment periods. Built with modern web technologies and designed for accessibility, it ensures every voice can be heard in the democratic process.

🛠️ Tech Stack

• Frontend: React 18 + TypeScript + Tailwind CSS
• Backend: Supabase (PostgreSQL + Auth + Storage + Edge Functions)
• Testing: Vitest + Cypress + Playwright
• Deployment: Netlify (Frontend) + Supabase (Backend)
• CI/CD: GitHub Actions

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn
• Supabase account

Setup

# Clone repository
git clone https://github.com/MetaPhase-Consulting/opencomments.git
cd opencomments

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Configure your Supabase credentials in .env
# VITE_SUPABASE_URL=https://your-project.supabase.co
# VITE_SUPABASE_ANON_KEY=your-anon-key

# Apply database migrations
npm run db:migrate

# Start development server
npm run dev

Visit http://localhost:5173 to see the application.

📁 Folder Structure

opencomments/
├── src/
│   ├── components/          # Reusable UI components
│   ├── pages/              # Route components
│   │   ├── agency/         # Agency admin portal
│   │   └── public/         # Public-facing pages
│   ├── hooks/              # Custom React hooks
│   ├── contexts/           # React context providers
│   ├── lib/                # Utilities and configurations
│   └── types/              # TypeScript type definitions
├── supabase/
│   ├── migrations/         # Database schema changes
│   └── functions/          # Edge functions
├── tests/                  # Test files
├── docs/                   # Documentation
└── public/                 # Static assets

🧪 Development

Testing (Current)

# Run unit tests
npm run test

# Typecheck
npm run typecheck

# Build
npm run build

Note: automated test coverage is being built out as part of the production hardening roadmap.

Database

# Apply migrations
npm run db:migrate

# Reset database (development only)
supabase db reset

Quality Assurance

Before deploying, ensure quality gates pass:

1. Lint: npm run lint
2. Typecheck: npm run typecheck
3. Build: npm run build
4. Test suite: npm run test:ci

📚 Documentation

• DEVELOPER.md - Development setup and workflows
• DEPLOYMENT_GUIDE.md - Production deployment instructions
• ARCHITECTURE.md - System design and technical overview
• DATAMODEL.md - Database schema and relationships
• API_V1.md - Public and agency API contract (v1)
• DATA_DICTIONARY.md - Canonical domain field definitions
• RBAC_ACCOUNT_ORG_MANAGEMENT.md - Enterprise role, account, and organization management model
• MIGRATION_VALIDATION.md - Fresh database migration replay validation process
• AGENCY_ONBOARDING.md - First-time agency setup guide
• AGENCY_ADMIN_GUIDE.md - Guide for government staff
• PUBLIC_USER_GUIDE.md - Guide for citizens
• OPERATIONS_RUNBOOK.md - Production operations guide
• OBSERVABILITY.md - Logging, metrics, and alerting baseline
• SECURITY_AUDIT_GUIDE.md - Security audit procedures
• CONTROL_MAPPING.md - Federal-ready control evidence mapping
• ACCESSIBILITY_TRACKER.md - Accessibility compliance tracking
• RELEASE_EVIDENCE_INDEX.md - Consolidated release evidence mapping
• PILOT_EXECUTION_GUIDE.md - Pilot execution procedure and evidence requirements
• PILOT_EXECUTION_REPORT.md - Latest pilot run outcomes and closure evidence
• PILOT_FINDINGS.md - Append-only pilot findings log
• PERFORMANCE_NOTES.md - Performance optimization guide

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: Check the docs/ folder for detailed guides
• Issues: Report bugs via GitHub Issues
• Support: Available through our contact form

---

Built with ❤️ for transparent government