How harshs16/civix works
Project type and purpose
• This is a full-stack civic issue reporting web application (“Civix”) with a React-based frontend and a Node.js/Express backend, persisting data in PostgreSQL and integrating with Cloudinary for file storage. It provides separate citizen and admin flows, real-time status tracking, voting/upvoting, civic education modules, and an interactive frontend-only simulator.
File structure
• Top-level “backend” directory: Express.js app following MVC
• controllers/, models/, routes/
• middlewares/ for security, validation, file upload
• config/ holds db and swagger configuration
• utils/ for email, token handling, Cloudinary integration
• uploads/ stores local file artifacts
• Top-level “src” directory: React SPA
• Pages/ for each route
• components/ reusable UI pieces (auth, modals, voting widgets)
• hooks/, utils/, assets/
• index.jsx, App.jsx bootstrap the app
• public/: Static assets (index.html, manifest, GTFS data CSVs/JSONs)
• cypress/: E2E tests
• jest/vitest setup for unit/integration tests
README for additional insights
• Backend: PostgreSQL, JWT auth, multer file uploads, express-validator, Helmet, rate limiting, Swagger UI
• Frontend: React, Tailwind CSS, Leaflet for maps, dark mode toggle, localStorage persistence
• Two frontend-only modules: Civic Education, Civic Simulator
a. Main components
• Client (Browser/React SPA)
• API Gateway (Express.js server)
• Database (PostgreSQL)
• File Storage (Cloudinary + local uploads backup)
• Authentication (JWT service, token store)
• Caching (in-memory or contributors.json cache)
• Third-party services (Swagger UI, Stripe-like push notifications—future)
b. Relationships & interactions
• React SPA sends HTTP(S) requests (REST) to Express API
• API uses middlewares for CSRF, XSS sanitization, rate limiting, auth checks
• After auth, API processes business logic in controllers, queries PostgreSQL, and uses Cloudinary SDK to upload/download images
• API returns JSON payloads; React updates UI, stores tokens in localStorage, caches some data locally
• Module (Leaflet) fetches location data from public/gtfs or backend endpoints
• E2E tests hit public index.html, perform flows via API
c. Architectural patterns & principles
• MVC on backend (Models + Controllers + Routes)
• RESTful API design
• JWT-based stateless authentication, role-based access control
• Middleware pipeline for cross-cutting concerns (security, file handling)
• React component hierarchy + hooks for separation of concerns
• LocalStorage for client state persistence (dark mode, simulator XP)
d. Key technologies
• Frontend: React, Tailwind CSS, Leaflet.js, React Router
• Backend: Node.js, Express.js, Swagger, Helmet, express-validator, multer
• Database: PostgreSQL (with Sequelize or raw queries)
• Storage: Cloudinary, local file store
• Testing: Jest/Supertest, Vitest/RTL, Cypress
Detail
• Separate routes (/api/auth, /api/issues, /api/contributions, /api/profile)
• Swagger at /api-docs as a self-documenting API endpoint
• File upload flow: React → multer middleware → Cloudinary → DB
• Frontend-only modules (CivicEducation, CivicSimulator) connecting purely to localStorage/logic