sansyuh06/polyclass

Purpose and deployment shape

PolyClass is a classroom prediction-market platform: authenticated students submit and trade YES/NO markets with virtual credits; moderators approve, resolve, and administer activity. It is a React single-page frontend backed by a Flask API. Production separates hosting: Vercel serves the frontend and Render runs the backend. Key deployment artifacts: frontend/vercel.json, backend/render.yaml, backend/wsgi.py.

Application entry points

The Flask application is assembled in backend/app/__init__.py, exposed for WSGI through backend/wsgi.py, and provides operational commands through backend/app/cli.py (including database initialization). The browser app mounts React in frontend/src/main.jsx and routes/page composition begin in frontend/src/App.jsx.

API, sessions, and authorization boundary

backend/app/api.py is the principal HTTP boundary for market, trading, portfolio, leaderboard, and moderator operations. Authentication and Google OAuth handling live in backend/app/auth.py; authenticated session lifecycle and request identity are handled in backend/app/sessions.py. This boundary enforces authorized-user access, moderator permissions, CSRF/session security, rate limiting, and frontend-origin integration.

Market domain and trade execution

Market mechanics are concentrated in backend/app/amm.py, with supporting domain rules/constants in backend/app/constants.py. The trading flow is: client requests an action through the API; backend validates user/session and market state; AMM logic prices and executes YES/NO share changes; balances, positions, and market state are persisted atomically. Resolution converts final outcome into account settlement and leaderboard/portfolio-visible state.

Persistence and lifecycle operations

backend/app/db.py owns database connectivity and query/persistence access across SQLite development and PostgreSQL production, with the relational model defined in backend/app/schema.sql. backend/app/maintenance.py contains lifecycle/operational work such as cleanup or periodic state maintenance. The database is the consistency boundary for users, credentials/balances, markets, orders/positions, moderation state, and resolved outcomes.

Moderation and governance

Moderator-specific policy and operations are isolated in backend/app/mod.py and exposed via the API layer. The frontend moderator workspace is frontend/src/pages/Mod.jsx. Moderators approve or reject submitted markets, resolve markets, and manage users/credits; this creates a privileged control path distinct from normal student trading.

Frontend client flows

frontend/src/api.js centralizes browser-to-Flask requests and session-aware API interaction. User workflows are represented by market discovery/trading (frontend/src/pages/Market.jsx, frontend/src/pages/Floor.jsx), market creation (frontend/src/pages/Create.jsx), and account outcomes (frontend/src/pages/Portfolio.jsx, frontend/src/pages/Leaderboard.jsx). The frontend is presentation/state orchestration only; authoritative validation, pricing, and settlement remain in the backend.

External services and runtime dependencies

The system runs Python/Flask with SQLite locally or PostgreSQL via DATABASE_URL in production, plus React/Vite in the browser build pipeline. Google OAuth 2.0 is the external identity provider. Environment-driven controls include session secret, allowed email domain, production mode, database connection, and frontend URL/CORS relationship.