|
| 1 | +# AI CoReasoning Lab |
| 2 | + |
| 3 | +A co-reasoning assessment platform where students develop critical thinking skills by collaborating with AI. Students frame ill-defined problems, judge AI-generated solutions, and steer the AI toward better outputs -- all while receiving LLM-evaluated feedback. |
| 4 | + |
| 5 | +## Key Features |
| 6 | + |
| 7 | +- **Three-Phase Challenge Runs** -- Framing, Judging, and Steering phases that assess co-reasoning skills |
| 8 | +- **Multiple Response Types** -- Multiple choice (MC) or open-ended responses per phase |
| 9 | +- **LLM-Powered Evaluation** -- Automated grading and feedback via OpenAI, Groq, or other providers |
| 10 | +- **Practice & Assessment Modes** -- Practice shows feedback after each phase; assessment reveals results only at completion |
| 11 | +- **Multilingual Support** -- English, Hebrew, French, German, and Spanish UI with separate content language for LLM prompts |
| 12 | +- **Role-Based Access** -- Student, Instructor, and Admin roles with appropriate permissions |
| 13 | +- **Course Management** -- Hierarchical subject trees, course subscriptions, instructor assignments |
| 14 | +- **Analytics & Reporting** -- Per-student and per-course analytics with PDF export |
| 15 | +- **Bulk Import** -- YAML-based import of institutions, users, courses, and challenges |
| 16 | + |
| 17 | +## Tech Stack |
| 18 | + |
| 19 | +| Layer | Technology | |
| 20 | +|-------|-----------| |
| 21 | +| **Runtime** | Node.js >= 20 | |
| 22 | +| **Framework** | Express 4.x | |
| 23 | +| **Database** | SQLite (dev/test) / PostgreSQL 16 (staging/prod) | |
| 24 | +| **ORM** | Knex.js 3.x | |
| 25 | +| **Auth** | Passport.js (local email/password + Google OAuth 2.0) | |
| 26 | +| **LLM** | OpenAI SDK (gpt-4o-mini default, gpt-4o full) + Groq (llama-3.3-70b fallback) | |
| 27 | +| **Validation** | Zod | |
| 28 | +| **Sessions** | express-session (memory store for SQLite, connect-pg-simple for PostgreSQL) | |
| 29 | +| **PDF** | PDFKit | |
| 30 | +| **Logging** | Winston | |
| 31 | +| **Security** | Helmet, CORS, bcryptjs | |
| 32 | +| **Tests** | Jest + Supertest (unit/integration), Playwright + Chromium (e2e) | |
| 33 | + |
| 34 | +## Project Structure |
| 35 | + |
| 36 | +``` |
| 37 | +code/ |
| 38 | + client/ # Static frontend (HTML pages, JS, CSS) |
| 39 | + js/ # Client-side JavaScript modules |
| 40 | + content-compiled/ # Compiled i18n bundles (en.js, he.js, etc.) |
| 41 | + styles.css # Application stylesheet |
| 42 | + *.html # Page templates (SPA-style, served statically) |
| 43 | + server/ |
| 44 | + index.js # Express app entry point |
| 45 | + routes/ # API route handlers |
| 46 | + services/ # Business logic layer |
| 47 | + middleware/ # Auth, validation, error handling, logging |
| 48 | + db/ |
| 49 | + knexfile.js # Database configuration |
| 50 | + migrations/ # Schema migrations |
| 51 | + seeds/ # Seed data |
| 52 | + llm/ |
| 53 | + prompt-engine.js # YAML prompt template loader and renderer |
| 54 | + utils/ # Constants, errors, helpers, logger, tracing |
| 55 | + prompts/ # LLM prompt templates (YAML) |
| 56 | + content/ # i18n content source files (YAML) |
| 57 | + en/ # English UI labels, tooltips, scenarios |
| 58 | + he/ # Hebrew |
| 59 | + fr/ de/ es/ # French, German, Spanish |
| 60 | + import/ |
| 61 | + sample/ # Sample import YAML files |
| 62 | + tests/ |
| 63 | + unit/ # Jest unit tests |
| 64 | + integration/ # Jest + Supertest API tests |
| 65 | + e2e/ # Playwright browser tests |
| 66 | + setup.js # Test environment setup |
| 67 | + docker/ # Docker and docker-compose files |
| 68 | + render.yaml # Render.com deployment blueprint |
| 69 | +``` |
| 70 | + |
| 71 | +## Getting Started |
| 72 | + |
| 73 | +### Prerequisites |
| 74 | + |
| 75 | +- Node.js >= 20.0.0 |
| 76 | +- npm |
| 77 | +- (Optional) PostgreSQL 16 for production-like setup |
| 78 | +- (Optional) Docker and Docker Compose |
| 79 | + |
| 80 | +### Installation |
| 81 | + |
| 82 | +```bash |
| 83 | +cd code |
| 84 | +npm install |
| 85 | +``` |
| 86 | + |
| 87 | +### Environment Variables |
| 88 | + |
| 89 | +Create a `.env.all` file in the `code/` directory: |
| 90 | + |
| 91 | +```env |
| 92 | +# Required |
| 93 | +SESSION_SECRET=your-random-secret-string |
| 94 | +
|
| 95 | +# LLM Providers (at least one recommended) |
| 96 | +OPENAI_API_KEY=sk-... |
| 97 | +GROQ_API_KEY=gsk_... |
| 98 | +
|
| 99 | +# Optional: Override default models |
| 100 | +OPENAI_MODEL=gpt-4o-mini |
| 101 | +OPENAI_MODEL_FULL=gpt-4o |
| 102 | +GROQ_MODEL=llama-3.3-70b-versatile |
| 103 | +
|
| 104 | +# Optional: Google OAuth |
| 105 | +GOOGLE_OAUTH_CLIENT_ID=... |
| 106 | +GOOGLE_OAUTH_CLIENT_SECRET=... |
| 107 | +
|
| 108 | +# Optional: PostgreSQL (defaults to SQLite for development) |
| 109 | +DATABASE_URL=postgres://user:password@localhost:5432/coreason |
| 110 | +
|
| 111 | +# Optional: Other LLM providers |
| 112 | +GEMINI_API_KEY=... |
| 113 | +COHERE_API_KEY=... |
| 114 | +``` |
| 115 | + |
| 116 | +If no LLM API keys are set, the application runs with fallback placeholder responses for all LLM features. |
| 117 | + |
| 118 | +### Database Setup |
| 119 | + |
| 120 | +```bash |
| 121 | +# Run migrations and seed data |
| 122 | +npm run db:setup |
| 123 | + |
| 124 | +# Or step by step: |
| 125 | +npm run db:migrate |
| 126 | +npm run db:seed |
| 127 | +``` |
| 128 | + |
| 129 | +### Build Content |
| 130 | + |
| 131 | +Compile i18n YAML content into JavaScript bundles: |
| 132 | + |
| 133 | +```bash |
| 134 | +npm run build |
| 135 | +``` |
| 136 | + |
| 137 | +### Run the Server |
| 138 | + |
| 139 | +```bash |
| 140 | +# Development (with auto-reload) |
| 141 | +npm run dev |
| 142 | + |
| 143 | +# Production |
| 144 | +npm start |
| 145 | +``` |
| 146 | + |
| 147 | +The server starts on `http://localhost:3000` by default. |
| 148 | + |
| 149 | +### Import Sample Data |
| 150 | + |
| 151 | +```bash |
| 152 | +npm run import -- import/sample/full-import.yaml |
| 153 | +``` |
| 154 | + |
| 155 | +This populates the database with demo institutions, users, courses (with subject trees), and challenges in both English and Hebrew. |
| 156 | + |
| 157 | +## Running Tests |
| 158 | + |
| 159 | +```bash |
| 160 | +# All tests |
| 161 | +npm run test:all |
| 162 | + |
| 163 | +# Unit tests only |
| 164 | +npm run test:unit |
| 165 | + |
| 166 | +# Integration tests (API tests with supertest) |
| 167 | +npm run test:integration |
| 168 | + |
| 169 | +# End-to-end tests (requires running server) |
| 170 | +npm run test:e2e |
| 171 | +``` |
| 172 | + |
| 173 | +### Test Configuration |
| 174 | + |
| 175 | +- **Unit tests**: Jest with Node environment, coverage thresholds at 80% lines/functions/statements and 70% branches |
| 176 | +- **Integration tests**: Jest + Supertest against in-memory SQLite |
| 177 | +- **E2E tests**: Playwright with Chromium, auto-starts dev server on port 3000 |
| 178 | + |
| 179 | +### Linting & Formatting |
| 180 | + |
| 181 | +```bash |
| 182 | +npm run lint |
| 183 | +npm run lint:fix |
| 184 | +npm run format |
| 185 | +``` |
| 186 | + |
| 187 | +## Docker |
| 188 | + |
| 189 | +```bash |
| 190 | +# Development (SQLite, auto-reload) |
| 191 | +npm run docker:dev |
| 192 | + |
| 193 | +# Production (PostgreSQL) |
| 194 | +npm run docker:prod |
| 195 | +``` |
| 196 | + |
| 197 | +The production Docker setup uses a multi-stage build (Node 20 Alpine) with `tini` as the init process and PostgreSQL 16 Alpine as the database. |
| 198 | + |
| 199 | +## Deployment |
| 200 | + |
| 201 | +### Render.com |
| 202 | + |
| 203 | +The project includes a `render.yaml` blueprint for one-click deployment to Render: |
| 204 | + |
| 205 | +- **Web service**: Free plan, Oregon region, Node runtime |
| 206 | +- **Database**: PostgreSQL (free plan) |
| 207 | +- **Build**: `npm install && npm run build && npm run db:setup` |
| 208 | +- **Start**: `node server/index.js` |
| 209 | + |
| 210 | +Required environment variables on Render: |
| 211 | +- `OPENAI_API_KEY` or `GROQ_API_KEY` (for LLM features) |
| 212 | +- `GOOGLE_OAUTH_CLIENT_ID` and `GOOGLE_OAUTH_CLIENT_SECRET` (for Google login) |
| 213 | +- `SESSION_SECRET` (auto-generated by Render) |
| 214 | +- `DATABASE_URL` (auto-linked from Render PostgreSQL) |
| 215 | + |
| 216 | +## API Overview |
| 217 | + |
| 218 | +All API endpoints are prefixed with `/api/v1/`. See the [Developer Guide](docs/developer-guide.md) for the complete API reference. |
| 219 | + |
| 220 | +| Route Group | Base Path | Description | |
| 221 | +|------------|-----------|-------------| |
| 222 | +| Auth | `/api/v1/auth` | Register, login, logout, Google OAuth, test-login | |
| 223 | +| Users | `/api/v1/users` | Profile management, stats | |
| 224 | +| Institutions | `/api/v1/institutions` | List and retrieve institutions | |
| 225 | +| Courses | `/api/v1/courses` | CRUD, subscriptions, subject trees, LLM generation | |
| 226 | +| Challenges | `/api/v1/challenges` | CRUD, publish, archive, preview | |
| 227 | +| Runs | `/api/v1/runs` | Start runs, submit phases, complete, reports | |
| 228 | +| Analytics | `/api/v1/analytics` | Student and instructor analytics, PDF export | |
| 229 | +| Import | `/api/v1/import` | YAML batch import | |
| 230 | +| LLM | `/api/v1/llm` | Preview generation, model listing | |
| 231 | +| Admin | `/api/v1/admin` | System overview, user/course/challenge management | |
| 232 | +| Health | `/api/health` | Health check (database + LLM status) | |
| 233 | + |
| 234 | +## License |
| 235 | + |
| 236 | +Proprietary. All rights reserved. |
0 commit comments