# batyle/lewissee architecture

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

- Interactive diagram: https://gitdiagram.com/batyle/lewissee
- Repository: https://github.com/batyle/lewissee

## Overview

FaceAttend is a face-based attendance product with instructor access and administration. Staff access the React app, enroll students, and scan camera frames; attendance is recorded only after face recognition and a liveness check. Admins manage instructor access requests and class blocks. The repository includes both a Python attendance/liveness service and Node/Vercel admin and instructor APIs; the README documents these deployment roles, but the excerpts do not establish every implementation-level connection. The main scan-to-service links below are therefore grounded in the README.

Main entry points: [`src/ScannerWorkspace.jsx`](https://github.com/batyle/lewissee/blob/main/src/ScannerWorkspace.jsx) (Attendance scanner), [`liveness-server/app.py`](https://github.com/batyle/lewissee/blob/main/liveness-server/app.py) (Liveness API), [`src/App.jsx`](https://github.com/batyle/lewissee/blob/main/src/App.jsx) (React app), [`api/[...path].js`](https://github.com/batyle/lewissee/blob/main/api/%5B...path%5D.js) (Vercel API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Staff web app"]
  node_app["React app<br/>[App.jsx]"]
  node_scanner["Attendance scanner"]
  node_student_admin["Student enrollment"]
  node_admin_ui["Admin pages<br/>[Instructors.jsx]"]
  node_admin_auth["Admin session<br/>[AuthContext.jsx]"]
  node_admin_api_client["Admin API client<br/>[adminApi.js]"]
end

subgraph group_attendance["Attendance services"]
  node_liveness_api["Liveness API<br/>[app.py]"]
  node_face_liveness["Face liveness<br/>[liveness.py]"]
  node_face_embeddings["Face recognition<br/>[embeddings.py]"]
  node_attendance_store["Attendance records<br/>[attendance.py]"]
end

subgraph group_access["Access management"]
  node_admin_functions["Vercel API<br/>[&#91;...path&#93;.js]"]
  node_admin_db_helpers["Database access<br/>[database.js]"]
  node_instructor_auth["Instructor access API"]
  node_node_routes["Node API routes<br/>[server.js]"]
  node_block_api["Class blocks<br/>[blockRoutes.js]"]
end

subgraph group_data["Persistent data"]
  node_mysql[("MySQL database")]
end

node_staff(("Staff"))
node_emailjs["EmailJS"]

node_staff -->|"uses"| node_app
node_app -.->|"routes to"| node_scanner
node_app -.->|"routes to"| node_student_admin
node_app -->|"routes to"| node_admin_ui
node_admin_ui -->|"requests"| node_admin_api_client
node_admin_auth -->|"authenticates via"| node_admin_api_client
node_admin_api_client -.->|"calls"| node_admin_functions
node_scanner -.->|"recognizes faces"| node_face_embeddings
node_scanner -->|"submits frames"| node_liveness_api
node_liveness_api -.->|"checks liveness"| node_face_liveness
node_liveness_api -.->|"recognizes faces"| node_face_embeddings
node_liveness_api -.->|"records attendance"| node_attendance_store
node_scanner -->|"requests attendance"| node_liveness_api
node_scanner -.->|"sends check-in email"| node_emailjs
node_admin_functions -->|"uses"| node_admin_db_helpers
node_admin_functions -->|"reads and writes"| node_mysql
node_admin_db_helpers -.->|"connects to"| node_mysql
node_node_routes -->|"routes to"| node_instructor_auth
node_node_routes -->|"routes to"| node_block_api
node_instructor_auth -->|"reads and writes"| node_mysql
node_block_api -->|"reads blocks"| node_mysql

click node_app "https://github.com/batyle/lewissee/blob/main/src/App.jsx"
click node_scanner "https://github.com/batyle/lewissee/blob/main/src/ScannerWorkspace.jsx"
click node_student_admin "https://github.com/batyle/lewissee/blob/main/src/ScannerWorkspace.jsx"
click node_admin_ui "https://github.com/batyle/lewissee/blob/main/src/pages/Instructors.jsx"
click node_admin_auth "https://github.com/batyle/lewissee/blob/main/src/context/AuthContext.jsx"
click node_admin_api_client "https://github.com/batyle/lewissee/blob/main/src/api/adminApi.js"
click node_liveness_api "https://github.com/batyle/lewissee/blob/main/liveness-server/app.py"
click node_face_liveness "https://github.com/batyle/lewissee/blob/main/passive_attendance/liveness.py"
click node_face_embeddings "https://github.com/batyle/lewissee/blob/main/passive_attendance/embeddings.py"
click node_attendance_store "https://github.com/batyle/lewissee/blob/main/passive_attendance/attendance.py"
click node_admin_functions "https://github.com/batyle/lewissee/blob/main/api/%5B...path%5D.js"
click node_admin_db_helpers "https://github.com/batyle/lewissee/blob/main/api/_lib/database.js"
click node_instructor_auth "https://github.com/batyle/lewissee/blob/main/server/controllers/instructorAuthController.js"
click node_node_routes "https://github.com/batyle/lewissee/blob/main/server/server.js"
click node_block_api "https://github.com/batyle/lewissee/blob/main/server/routes/blockRoutes.js"

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_app,node_scanner,node_student_admin,node_admin_ui,node_admin_auth,node_admin_api_client toneBlue
class node_liveness_api,node_face_liveness,node_face_embeddings,node_attendance_store toneAmber
class node_admin_functions,node_admin_db_helpers,node_instructor_auth,node_node_routes,node_block_api toneMint
class node_mysql toneRose
class node_staff,node_emailjs toneIndigo
```

## Components

### Staff web app

- [React app](https://github.com/batyle/lewissee/blob/main/src/App.jsx): `src/App.jsx`
- [Attendance scanner](https://github.com/batyle/lewissee/blob/main/src/ScannerWorkspace.jsx): `src/ScannerWorkspace.jsx`
- [Student enrollment](https://github.com/batyle/lewissee/blob/main/src/ScannerWorkspace.jsx): `src/ScannerWorkspace.jsx`
- [Admin pages](https://github.com/batyle/lewissee/blob/main/src/pages/Instructors.jsx): `src/pages/Instructors.jsx`
- [Admin session](https://github.com/batyle/lewissee/blob/main/src/context/AuthContext.jsx): `src/context/AuthContext.jsx`
- [Admin API client](https://github.com/batyle/lewissee/blob/main/src/api/adminApi.js): `src/api/adminApi.js`

### Attendance services

- [Liveness API](https://github.com/batyle/lewissee/blob/main/liveness-server/app.py): `liveness-server/app.py`
- [Face liveness](https://github.com/batyle/lewissee/blob/main/passive_attendance/liveness.py): `passive_attendance/liveness.py`
- [Face recognition](https://github.com/batyle/lewissee/blob/main/passive_attendance/embeddings.py): `passive_attendance/embeddings.py`
- [Attendance records](https://github.com/batyle/lewissee/blob/main/passive_attendance/attendance.py): `passive_attendance/attendance.py`

### Access management

- [Vercel API](https://github.com/batyle/lewissee/blob/main/api/%5B...path%5D.js): `api/[...path].js`
- [Database access](https://github.com/batyle/lewissee/blob/main/api/_lib/database.js): `api/_lib/database.js`
- [Instructor access API](https://github.com/batyle/lewissee/blob/main/server/controllers/instructorAuthController.js): `server/controllers/instructorAuthController.js`
- [Node API routes](https://github.com/batyle/lewissee/blob/main/server/server.js): `server/server.js`
- [Class blocks](https://github.com/batyle/lewissee/blob/main/server/routes/blockRoutes.js): `server/routes/blockRoutes.js`

### Persistent data

- **MySQL database**

### Other components

- **Staff**
- **EmailJS**

## Connections

- Staff → React app: uses (evidence: `src/App.jsx`)
- React app → Attendance scanner: routes to
- React app → Student enrollment: routes to
- React app → Admin pages: routes to (evidence: `src/App.jsx`)
- Admin pages → Admin API client: requests (evidence: `src/pages/Instructors.jsx`)
- Admin session → Admin API client: authenticates via (evidence: `src/context/AuthContext.jsx`)
- Admin API client → Vercel API: calls
- Attendance scanner → Face recognition: recognizes faces
- Attendance scanner → Liveness API: submits frames
- Liveness API → Face liveness: checks liveness
- Liveness API → Face recognition: recognizes faces
- Liveness API → Attendance records: records attendance
- Attendance scanner → Liveness API: requests attendance
- Attendance scanner → EmailJS: sends check-in email
- Vercel API → Database access: uses (evidence: `api/[...path].js`)
- Vercel API → MySQL database: reads and writes
- Database access → MySQL database: connects to
- Node API routes → Instructor access API: routes to (evidence: `server/server.js`)
- Node API routes → Class blocks: routes to (evidence: `server/server.js`)
- Instructor access API → MySQL database: reads and writes (evidence: `server/controllers/instructorAuthController.js`)
- Class blocks → MySQL database: reads blocks (evidence: `server/routes/blockRoutes.js`)