# parthsolanke/coneixement-stem-consulting architecture

> Architecture diagram of the GitHub repository parthsolanke/coneixement-stem-consulting, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/parthsolanke/coneixement-stem-consulting
- Repository: https://github.com/parthsolanke/coneixement-stem-consulting

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Web Client
    subgraph "Web Client (Browser)"
        direction TB
        UI["UI Components"]:::frontend
        QuizPage["Quiz Page"]:::frontend
        ReportPage["Report Page"]:::frontend
        AgeSelect["Age Selection"]:::frontend
        ContactUs["Contact Us"]:::frontend
    end

    %% Frontend Server
    subgraph "Frontend Server (Next.js)"
        direction TB
        NextApp["Next.js Server"]:::frontend
        API_SendEmail["send-email API Route"]:::frontend
        PDFGen["pdfGenerator Utility"]:::frontend
        MiddlewareFE["Frontend Middleware"]:::frontend
        DrizzleConfig["Drizzle Config"]:::db
        DrizzleIndex["DB Entry Point"]:::db
        DrizzleSchema["Schema Definition"]:::db
        Queries["Query Helpers"]:::db
        EmailTemplateContact["Contact Form Template"]:::frontend
        EmailTemplateReport["Report Form Template"]:::frontend
    end

    %% Backend API Service
    subgraph "Backend API Service (Python)"
        direction TB
        Dockerfile["Dockerfile"]:::backend
        Dockerignore[".dockerignore"]:::backend
        BE_Server["server.py"]:::backend
        BE_Middleware["Error Handlers"]:::backend
        QuizRoutes["Quiz Routes"]:::backend
        QuizUtils["quiz_utils"]:::backend
        ReportRoutes["Report Routes"]:::backend
        ReportUtils["report_utils"]:::backend
        Config["config"]:::backend
        Context["context"]:::backend
        LLMUtils["llm_utils"]:::external
        Models1["Data Models"]:::backend
        Models2["Report Sections"]:::backend
    end

    %% Database and External Services
    DB["Database"]:::db
    LLM["External LLM Service"]:::external
    EmailSvc["Email Delivery Service"]:::external

    %% Testing
    TestSuite["Test Suite"]:::external

    %% User Flow
    User["User"]:::external
    User --> UI
    UI --> NextApp
    QuizPage --> NextApp
    ReportPage --> NextApp
    AgeSelect --> NextApp
    ContactUs --> NextApp

    %% Frontend ORM & Middleware
    NextApp -->|imports| MiddlewareFE
    NextApp -->|ORM query| DrizzleIndex
    DrizzleIndex --> DrizzleSchema
    DrizzleIndex --> Queries
    NextApp -->|reads config| DrizzleConfig

    %% Frontend to Backend API
    NextApp -->|"POST /api/quiz"| BE_Server
    NextApp -->|"POST /api/report"| BE_Server

    %% PDF & Email
    NextApp --> PDFGen
    PDFGen --> UI
    NextApp --> API_SendEmail
    API_SendEmail --> EmailSvc
    API_SendEmail --> EmailTemplateContact
    API_SendEmail --> EmailTemplateReport

    %% Backend internals
    BE_Server --> BE_Middleware
    BE_Server --> QuizRoutes
    BE_Server --> ReportRoutes
    QuizRoutes --> QuizUtils
    ReportRoutes --> ReportUtils
    QuizUtils --> LLMUtils
    ReportUtils --> LLMUtils
    ReportUtils --> Models1
    ReportUtils --> Models2
    LLMUtils --> LLM

    %% Tests
    TestSuite --> NextApp
    TestSuite --> BE_Server

    %% Click Events
    click UI "https://github.com/parthsolanke/coneixement-stem-consulting/tree/main/frontend/app/Components"
    click QuizPage "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/frontend/app/quiz/page.js"
    click ReportPage "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/frontend/app/report/page.js"
    click AgeSelect "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/frontend/app/ageSelect/page.js"
    click ContactUs "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/frontend/app/contactus/page.js"
    click API_SendEmail "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/frontend/app/api/send-email/route.js"
    click PDFGen "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/frontend/app/report/utils/pdfGenerator.js"
    click DrizzleSchema "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/frontend/server/db/schema.ts"
    click DrizzleIndex "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/frontend/server/db/index.ts"
    click Queries "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/frontend/server/queries.ts"
    click DrizzleConfig "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/frontend/drizzle.config.ts"
    click MiddlewareFE "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/frontend/middleware.ts"
    click EmailTemplateContact "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/frontend/templates/emails/contact-form.jsx"
    click EmailTemplateReport "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/frontend/templates/emails/report-form.jsx"
    click BE_Server "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/backend/api/server.py"
    click QuizRoutes "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/backend/api/quiz/routes.py"
    click QuizUtils "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/backend/api/quiz/quiz_utils.py"
    click ReportRoutes "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/backend/api/report/routes.py"
    click ReportUtils "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/backend/api/report/report_utils.py"
    click BE_Middleware "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/backend/api/middleware/error_handlers.py"
    click Config "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/backend/api/utils/config.py"
    click Context "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/backend/api/utils/context.py"
    click LLMUtils "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/backend/api/utils/llm_utils.py"
    click Models1 "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/backend/api/utils/models.py"
    click Models2 "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/backend/api/utils/report_sections.py"
    click Dockerfile "https://github.com/parthsolanke/coneixement-stem-consulting/tree/main/backend/Dockerfile"
    click Dockerignore "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/backend/.dockerignore"
    click TestSuite "https://github.com/parthsolanke/coneixement-stem-consulting/blob/main/tests/test_report.py"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#3498DB,color:#1B4F72;
    classDef backend fill:#F9E79F,stroke:#D4AC0D,color:#7D6608;
    classDef db fill:#ABEBC6,stroke:#27AE60,color:#145A32;
    classDef external fill:#F5B7B1,stroke:#E74C3C,color:#922B21;
```
