# sansyuh06/polyclass architecture

> Architecture diagram of the GitHub repository sansyuh06/polyclass, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sansyuh06/polyclass
- Repository: https://github.com/sansyuh06/polyclass

## Overview

#### 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.

Main entry points: [`backend/app/api.py`](https://github.com/sansyuh06/polyclass/blob/master/backend/app/api.py) (HTTP API), [`backend/app/db.py`](https://github.com/sansyuh06/polyclass/blob/master/backend/app/db.py) (Database access), [`frontend/src/App.jsx`](https://github.com/sansyuh06/polyclass/blob/master/frontend/src/App.jsx) (App routes), [`frontend/src/api.js`](https://github.com/sansyuh06/polyclass/blob/master/frontend/src/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React frontend"]
  node_vercel{{"Vercel<br/>frontend host<br/>[vercel.json]"}}
  node_react_entry["React entry<br/>browser mount<br/>[main.jsx]"]
  node_app_shell["App routes<br/>page composition<br/>[App.jsx]"]
  node_client_api["API client<br/>session-aware requests<br/>[api.js]"]
  node_student_pages["Student workflows<br/>market and account pages<br/>[Market.jsx]"]
  node_moderator_ui["Moderator workspace<br/>privileged UI<br/>[Mod.jsx]"]
end

subgraph group_backend["Flask backend"]
  node_render{{"Render<br/>backend host<br/>[render.yaml]"}}
  node_wsgi["WSGI entry<br/>production entrypoint<br/>[wsgi.py]"]
  node_flask_app["Flask app assembly<br/>application factory<br/>[__init__.py]"]
  node_api["HTTP API<br/>API boundary<br/>[api.py]"]
  node_auth["Authentication<br/>OAuth handling<br/>[auth.py]"]
  node_sessions["Sessions and authorization<br/>request identity<br/>[sessions.py]"]
  node_amm["AMM trade engine<br/>market mechanics<br/>[amm.py]"]
  node_moderation["Moderation service<br/>governance policy<br/>[mod.py]"]
  node_maintenance["Lifecycle maintenance<br/>operational jobs<br/>[maintenance.py]"]
  node_cli["Operational CLI<br/>admin commands<br/>[cli.py]"]
end

subgraph group_data["Persistence"]
  node_database_access["Database access<br/>persistence layer<br/>[db.py]"]
  node_schema[("Relational schema<br/>data model<br/>[schema.sql]")]
end

node_google_oauth(("Google OAuth 2.0<br/>identity provider"))

node_vercel -->|"serves"| node_react_entry
node_react_entry -->|"mounts"| node_app_shell
node_app_shell -->|"routes to"| node_student_pages
node_app_shell -->|"routes to"| node_moderator_ui
node_student_pages -->|"requests"| node_client_api
node_moderator_ui -->|"requests"| node_client_api
node_client_api -->|"HTTPS API calls"| node_api
node_render -->|"runs"| node_wsgi
node_wsgi -->|"exposes"| node_flask_app
node_flask_app -->|"registers"| node_api
node_api -->|"validates identity"| node_sessions
node_api -->|"auth flows"| node_auth
node_auth -->|"OAuth exchange"| node_google_oauth
node_api -->|"trade actions"| node_amm
node_api -->|"privileged operations"| node_moderation
node_amm -->|"atomic market updates"| node_database_access
node_moderation -->|"approval and resolution"| node_database_access
node_maintenance -->|"cleanup and state work"| node_database_access
node_cli -->|"initializes and operates"| node_database_access
node_database_access -->|"persists model"| node_schema

click node_vercel "https://github.com/sansyuh06/polyclass/blob/master/frontend/vercel.json"
click node_react_entry "https://github.com/sansyuh06/polyclass/blob/master/frontend/src/main.jsx"
click node_app_shell "https://github.com/sansyuh06/polyclass/blob/master/frontend/src/App.jsx"
click node_client_api "https://github.com/sansyuh06/polyclass/blob/master/frontend/src/api.js"
click node_student_pages "https://github.com/sansyuh06/polyclass/blob/master/frontend/src/pages/Market.jsx"
click node_moderator_ui "https://github.com/sansyuh06/polyclass/blob/master/frontend/src/pages/Mod.jsx"
click node_render "https://github.com/sansyuh06/polyclass/blob/master/backend/render.yaml"
click node_wsgi "https://github.com/sansyuh06/polyclass/blob/master/backend/wsgi.py"
click node_flask_app "https://github.com/sansyuh06/polyclass/blob/master/backend/app/__init__.py"
click node_api "https://github.com/sansyuh06/polyclass/blob/master/backend/app/api.py"
click node_auth "https://github.com/sansyuh06/polyclass/blob/master/backend/app/auth.py"
click node_sessions "https://github.com/sansyuh06/polyclass/blob/master/backend/app/sessions.py"
click node_amm "https://github.com/sansyuh06/polyclass/blob/master/backend/app/amm.py"
click node_moderation "https://github.com/sansyuh06/polyclass/blob/master/backend/app/mod.py"
click node_maintenance "https://github.com/sansyuh06/polyclass/blob/master/backend/app/maintenance.py"
click node_cli "https://github.com/sansyuh06/polyclass/blob/master/backend/app/cli.py"
click node_database_access "https://github.com/sansyuh06/polyclass/blob/master/backend/app/db.py"
click node_schema "https://github.com/sansyuh06/polyclass/blob/master/backend/app/schema.sql"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_vercel,node_react_entry,node_app_shell,node_client_api,node_student_pages,node_moderator_ui toneBlue
class node_render,node_wsgi,node_flask_app,node_api,node_auth,node_sessions,node_amm,node_moderation,node_maintenance,node_cli toneAmber
class node_database_access,node_schema toneMint
class node_google_oauth toneNeutral
```

## Components

### React frontend

Vercel-hosted browser application.

- [Vercel](https://github.com/sansyuh06/polyclass/blob/master/frontend/vercel.json): frontend host · `frontend/vercel.json`
- [React entry](https://github.com/sansyuh06/polyclass/blob/master/frontend/src/main.jsx): browser mount · `frontend/src/main.jsx`
- [App routes](https://github.com/sansyuh06/polyclass/blob/master/frontend/src/App.jsx): page composition · `frontend/src/App.jsx`
- [API client](https://github.com/sansyuh06/polyclass/blob/master/frontend/src/api.js): session-aware requests · `frontend/src/api.js`
- [Student workflows](https://github.com/sansyuh06/polyclass/blob/master/frontend/src/pages/Market.jsx): market and account pages · Discovery, trading, creation, portfolio, and leaderboard views. · `frontend/src/pages/Market.jsx`
- [Moderator workspace](https://github.com/sansyuh06/polyclass/blob/master/frontend/src/pages/Mod.jsx): privileged UI · `frontend/src/pages/Mod.jsx`

### Flask backend

Render-hosted API and domain services.

- [Render](https://github.com/sansyuh06/polyclass/blob/master/backend/render.yaml): backend host · `backend/render.yaml`
- [WSGI entry](https://github.com/sansyuh06/polyclass/blob/master/backend/wsgi.py): production entrypoint · `backend/wsgi.py`
- [Flask app assembly](https://github.com/sansyuh06/polyclass/blob/master/backend/app/__init__.py): application factory · `backend/app/__init__.py`
- [HTTP API](https://github.com/sansyuh06/polyclass/blob/master/backend/app/api.py): API boundary · Serves market, trading, portfolio, leaderboard, and moderator operations. · `backend/app/api.py`
- [Authentication](https://github.com/sansyuh06/polyclass/blob/master/backend/app/auth.py): OAuth handling · `backend/app/auth.py`
- [Sessions and authorization](https://github.com/sansyuh06/polyclass/blob/master/backend/app/sessions.py): request identity · Enforces session, CSRF, access, and moderator boundaries. · `backend/app/sessions.py`
- [AMM trade engine](https://github.com/sansyuh06/polyclass/blob/master/backend/app/amm.py): market mechanics · Prices and executes YES/NO share changes. · `backend/app/amm.py`
- [Moderation service](https://github.com/sansyuh06/polyclass/blob/master/backend/app/mod.py): governance policy · Approves, resolves, and administers markets and credits. · `backend/app/mod.py`
- [Lifecycle maintenance](https://github.com/sansyuh06/polyclass/blob/master/backend/app/maintenance.py): operational jobs · `backend/app/maintenance.py`
- [Operational CLI](https://github.com/sansyuh06/polyclass/blob/master/backend/app/cli.py): admin commands · Includes database initialization. · `backend/app/cli.py`

### Persistence

Relational consistency boundary.

- [Database access](https://github.com/sansyuh06/polyclass/blob/master/backend/app/db.py): persistence layer · Selects SQLite locally or PostgreSQL through DATABASE_URL. · `backend/app/db.py`
- [Relational schema](https://github.com/sansyuh06/polyclass/blob/master/backend/app/schema.sql): data model · Stores users, balances, markets, positions, moderation, and outcomes. · `backend/app/schema.sql`

### Other components

- **Google OAuth 2.0**: identity provider

## Connections

- Vercel → React entry: serves
- React entry → App routes: mounts
- App routes → Student workflows: routes to
- App routes → Moderator workspace: routes to
- Student workflows → API client: requests
- Moderator workspace → API client: requests
- API client → HTTP API: HTTPS API calls
- Render → WSGI entry: runs
- WSGI entry → Flask app assembly: exposes
- Flask app assembly → HTTP API: registers
- HTTP API → Sessions and authorization: validates identity
- HTTP API → Authentication: auth flows
- Authentication → Google OAuth 2.0: OAuth exchange
- HTTP API → AMM trade engine: trade actions
- HTTP API → Moderation service: privileged operations
- AMM trade engine → Database access: atomic market updates
- Moderation service → Database access: approval and resolution
- Lifecycle maintenance → Database access: cleanup and state work
- Operational CLI → Database access: initializes and operates
- Database access → Relational schema: persists model