Add OpenAPI/Swagger documentation infrastructure for AI-assisted frontend development

[Copilot]

Overview

This PR implements comprehensive OpenAPI/Swagger documentation for the TallyJ Election Management System, enabling AI-assisted frontend development and establishing the foundation for decoupling the frontend from the .NET backend.

Problem Addressed

The current TallyJ implementation couples UI rendering and business logic, making upgrades and cross-platform integration difficult. This creates barriers for onboarding new users and developers, and prevents the use of modern AI tools for rapid frontend prototyping.

Solution

Added a complete REST API layer with OpenAPI 3.0 specification alongside the existing MVC application, providing:

API Infrastructure

• ASP.NET Web API configured alongside existing MVC framework
• RESTful endpoints with proper HTTP methods and status codes
• API versioning structure (/api/v1/...) for future compatibility
• JSON-first design with camel case property naming

Interactive Documentation

• Swagger UI accessible at /ApiDocs for live API testing
• OpenAPI 3.0 specification available at /api/v1/docs/openapi.json
• Comprehensive API reference with request/response examples
• Schema definitions with validation rules and constraints

Sample Implementation

Created a complete Elections API demonstrating:

GET    /api/v1/elections           # List all elections
POST   /api/v1/elections           # Create new election
GET    /api/v1/elections/{id}      # Get specific election
PUT    /api/v1/elections/{id}      # Update election
DELETE /api/v1/elections/{id}      # Delete election

Domain Model Documentation

• Entity relationship mapping for Election, Person, Ballot, Vote, Location, and Teller
• Data Transfer Objects (DTOs) with validation attributes
• Complete OpenAPI schema documenting all request/response models

AI Integration Ready

The implementation provides everything needed for AI-assisted frontend development:

• v0.dev compatibility: Import openapi.json to generate React components
• Figma React AI Developer: Convert designs to React using API schema
• OpenAPI Generator: Generate TypeScript/JavaScript clients
• Standard format: Widely supported by AI development tools

Example AI workflow:

// AI tools can now generate frontend code like:
const elections = await fetch('/api/v1/elections').then(r => r.json());
// With full type safety and validation

Backward Compatibility

• Zero impact on existing MVC application functionality
• Existing controllers continue to work unchanged
• Gradual migration path for moving to API-first architecture
• Dual support for both traditional views and modern API clients

Files Added

• openapi.json - Complete OpenAPI 3.0 specification
• API_DOCUMENTATION.md - Human-readable API reference
• Site/App_Start/WebApiConfig.cs - Web API configuration
• Site/Controllers/Api/ElectionsApiController.cs - Sample REST API
• Site/Models/DTOs/ - Data transfer objects with validation
• Site/Views/ApiDocs/Index.cshtml - Interactive documentation UI

Benefits

1. Faster Development: AI tools can generate modern frontends from the API specification
2. Better Onboarding: Interactive documentation makes the system more accessible
3. Future-Proof Architecture: Clean API separation enables multiple client applications
4. Type Safety: Strong typing through DTOs and OpenAPI schema
5. Self-Documenting: API documentation stays synchronized with code changes

This implementation addresses the core issue of difficult onboarding while providing a clear path for modernizing the frontend using AI-assisted development tools.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Experiment with AI tools for modern, more intuitive frontend.</issue_title>
<issue_description>##

We have had issues with onboarding people to use tallyj, and since there's a lot of time put on this platform we should consider upgrading, I can put together other devs who are interested to help the open source project if you wish. However, this is what I was thinking we should consider as we wait for AI to get better, claude code has gotten very good, as well as some other tools I have used.

Summary:

As part of the upcoming upgrade, we should decouple the existing frontend from the .NET service. This will allow the backend to operate as a dedicated REST API layer while enabling future frontends to be developed independently — including those generated through AI tools such as v0 and Figma’s React AI Developer.

Context

The current .NET implementation couples UI rendering and business logic, making upgrades and cross-platform integration difficult. By isolating a clean REST API layer, we can:

• Modernize the architecture and adopt a true client-server separation.

• Allow parallel development of multiple clients (web, mobile, admin dashboards).

• Support AI-assisted frontend generation from design prototypes or OpenAPI contracts.

Proposed Steps

1. Generate and document all REST endpoints using Swagger/OpenAPI

2. Verify if an existing spec is available (e.g., /swagger/v1/swagger.json).

3. If not, integrate Swashbuckle or NSwag into the .NET solution to expose it.

4. Export a openapi.json or openapi.yaml file to serve as the canonical API contract.

5. Map and document domain entities and their relationships i.e. ERD Diagram

6. Identify key entities

7. Describe one-to-many / many-to-many relationships and dependencies.

8. This ensures the API layer accurately reflects domain boundaries and data ownership.

Next Steps

1. Get AI to rebuild the backend based on domain entity and SQL tables into a pure REST API service (DDD and CLEAN)

2. Move UI logic out of .NET controllers.

3. Expose well-typed endpoints that match the OpenAPI schema.

4. Apply standard authentication and versioning (api/v1/...).

5. Develop a decoupled React frontend using AI

6. Use AI-assisted tools (e.g., v0, Figma React AI Developer) to generate the frontend from design specs or the OpenAPI schema.

7. Connect it to the new REST API layer for real-time data interactions.

Dependencies

✅ Add Swagger/OpenAPI specification (new ticket).

✅ Domain model documentation (ERD or schema mapping).

⏳ Backend endpoints finalised and exposed via REST.

Benefits

• Modular architecture and cleaner upgrade path.

• Reusable API layer across multiple frontends.

• Faster, AI-assisted frontend prototyping.

• Easier onboarding for new developers.

• Seperation will allow rapid prototyping on FE and BE, and we can move very quick using AI.

References

• v0.dev

• Figma React AI </issue_description>

<agent_instructions>This is an effort to modernize an older website. Still in discovery mode.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

Fixes glittle/TallyJ-4#2

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.