How parthsolanke/coneixement-stem-consulting works
Project type and purpose
• Type: Full-stack educational web application
• Purpose: Guide students (grades 8–12) through personality quizzes, generate STEM career recommendations and detailed reports, send reports via email.
High-level architecture & file-structure analysis
• Monorepo containing two main services:
a. frontend/ – Next.js 13 app with React components, server-side code, Drizzle ORM, Tailwind CSS, and built-in API routes (e.g., send-email).
b. backend/ – Python API service (containerized via Docker), organized under backend/api with submodules for quiz, report, middleware, LLM integration, error handling.
• Database – Defined in frontend/server/db via Drizzle (likely SQLite or PostgreSQL).
• External services – LLM provider (e.g. OpenAI) and an email delivery service (via the send-email function).
• Testing in tests/, infrastructure and deployment bits in .github/, Dockerfiles, .env examples.
Core components and boundaries
A. Web Client (Browser)
• React pages, UI components (Hero, Quiz UI, Report viewer).
B. Frontend Server (Next.js)
• Node.js runtime, Server Components, API Routes (send-email), PDF generator utility.
• Drizzle ORM → Database.
C. Backend API Service (Python)
• Exposes REST (or RPC) endpoints: /quiz, /report
• Middleware for error handling, context setup.
• Business logic: quiz_utils, report_utils, LLM calls.
D. Database
• Schema.ts, migrations via Drizzle.
• Stores user quiz answers, session data, logs.
E. External LLM Service
• OpenAI (or similar) called by backend/utils/llm_utils.py
F. Email Delivery Service
• SMTP or third-party (SendGrid, SES) used by frontend/api/send-email
Relationships & data flows
1. User interacts with → Web Client
2. Web Client fetches data / posts answers to → Frontend Server API or directly renders pages
3. Frontend Server may:
• Query Database via Drizzle (e.g., fetch past quizzes)
• Forward quiz answers to → Backend API (/api/quiz)
• Request report generation from → Backend API (/api/report)
4. Backend API:
• Validates request → calls LLM Service for narrative content → compiles report → returns JSON payload
5. Frontend Server:
• Receives report → invokes pdfGenerator utility → offers download or print
• Calls send-email API route → sends HTML/PDF via Email Delivery Service
Architectural patterns & technologies to highlight
• Separation of concerns: UI vs business logic vs data layer
• Micro-service style: Python API decoupled from Next.js front end
• Server-side rendering (SSR) & server actions in Next.js
• ORM layer (Drizzle) abstracting the database
• Middleware pattern in backend for error handling & context injection
• Containerization: Dockerfile in backend
Final checklist
• All major components (Client, Frontend Server, Backend API, Database, LLM, Email) represented
• Logical grouping inside service boundaries
• Call-outs for key frameworks/libraries