1. System Architecture and Technology Stack

The platform is built as a three-tier monorepo, architected for high security and multi-tenant scalability. It decouples administrative election creation from member-facing interaction, supported by a dedicated secure backend service.

Architect’s Note on Versioning: Vocdoni SDK version 0.9.1 is an absolute requirement. This specific version resolved critical Vite bundling issues that caused instability in earlier browser builds. All production clients must utilize the EnvOptions.PROD configuration.

——————————————————————————–

2. Secure Metadata and Storage Strategy

The architecture employs a hybrid storage strategy to balance the immutability of the blockchain with the performance requirements of large datasets.

Three-Tier Storage Locations

• Vocdoni Blockchain (Primary Storage): Stores core immutable metadata, such as organization name and election parameters. This ensures the “truth” of the election remains tamper-proof.
• IPFS/Pinata (Supplementary Data): Handles high-volume data categorized into three streams: Census Storage (voter lists), Discussion Storage (member comments), and Amendment Storage (detailed change requests).
• Local Memory/State: Manages runtime-specific data, including real-time UI updates, user-specific eligibility, and temporary vote status.

Secure Pinata Integration

Architect’s Note: The architecture eliminates key vulnerabilities by shielding all IPFS operations:

1. Backend Shielding: All Pinata API keys are stored exclusively as server-side environment variables on the pinata-backend.
2. API Decoupling: The frontend never communicates with Pinata directly. It calls secure backend endpoints (e.g., /api/store-census) which handles the pinning.
3. CORS Enforcement: The backend strictly enforces Cross-Origin Resource Sharing, limiting access only to authorized customer subdomains.

3. Aragon DAO integration (Optional)

• Metadata Formatting: To ensure “perfect visibility” within the Aragon OSx App dashboard, the bridge utilizes CID v1 and Flat JSON formatting.
• Audit Trail: The payload includes the full deliberative history, vote counts, amendment text, and the original Vocdoni Election ID for cryptographic auditability on Polygon.

4. Maintenance and Troubleshooting

• Problem: “Execution Failed: Proposal must pass.”
  • Solution: Verify the Vocdoni election period has ended and at least one vote was cast. The bridge will not execute a null or active result.
• Problem: “CORS Errors” on new customer subdomains.
  • Solution: Ensure the domain (including https://) is in the Heroku ALLOWED_ORIGINS var and the Heroku app has been restarted.
• Problem: “No Aragon DAO found.”
  • Solution: Check customer-config.ts to ensure the aragonDaoAddress is not null and matches the correct network ID.
• Problem: “Domain Not Working” / DNS Issues.
  • Solution: Verify CNAME records in GoDaddy match the Vercel-provided values exactly. Use a DNS checker to confirm propagation.
• Problem: “Chair Account Not Working.”
  • Solution: Verify the wallet address in customer-config.ts. Remember: addresses are case-sensitive in some SDK contexts.
• Problem: “Stuck/Pending MetaMask Transaction.”
  • Solution: The Polygon network often requires higher gas. Use the “Speed Up” feature to set gas prices to 80-100 Gwei.

——————————————————————————–

5. Production Deployment Checklist

• [ ] All Vocdoni SDK clients set to EnvOptions.PROD.
• [ ] API keys removed from frontend and confirmed in pinata-backend environment.
• [ ] ALLOWED_ORIGINS in Heroku updated with https:// prefix for all new domains.
• [ ] Heroku app restarted after configuration updates.
• [ ] Chair wallet funded with native POL on Polygon Mainnet.
• [ ] Vercel deployment branch set to production-main.
• [ ] Aragon Token Voting plugin permissions (CREATE_PROPOSAL_PERMISSION) granted to Chair wallet.
• [ ] Metadata verified as CID v1 in Pinata test run.
• [ ] HTTPS protocol verified for all API communication.

6. Scalability and Decentralized Indexing

To support 100+ customers without the bottleneck of a central database, RRD uses a decentralized indexing strategy via Pinata Metadata Tags.

The Discovery Workflow:

1. Tagging: During pinning, the backend attaches key-value tags: organizationName, electionId, and type.
2. Querying: The frontend calls /api/find-organization-proposals/:organizationName.
3. Filtering: The backend queries the Pinata API using the metadata[keyvalues] filter, returning all pins associated with that organization.
4. Resolution: The app extracts the election IDs from the tags and fetches the final “truth” directly from the Vocdoni blockchain.