# youcef3939/evalia architecture

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

- Interactive diagram: https://gitdiagram.com/youcef3939/evalia
- Repository: https://github.com/youcef3939/evalia

## Overview

1. **Overall shape**  
   EVALIA is a small **Next.js  App Router** application with a single end-to-end product flow: a user submits a pitch deck, the server evaluates it, and the UI displays investor-style feedback. There is no separate backend service; the main application and API live in the same repo.

2. **Primary user interface**  
   The frontend is centered in `src/app/page.tsx`, with shared app scaffolding in `src/app/layout.tsx` and global styling in `src/app/globals.css`. This is the presentation layer where users likely upload or paste deck content and see the evaluation result.

3. **Server boundary**  
   The main backend entry point is `src/app/api/evaluate/route.ts`. This route is the architecture boundary between the browser and the evaluation pipeline: it receives input from the UI, performs processing, and returns a structured assessment.

4. **Input model**  
   The README says the MVP accepts **PDF or structured text**. That means the system is designed around two ingestion modes, but both converge into text-based analysis rather than visual deck understanding.

5. **Document extraction subsystem**  
   `src/lib/pdfExtractor.ts` is responsible for converting PDF pitch decks into structured text. This is the first transformation step in the pipeline and acts as the bridge from raw document format to model-readable content.

6. **Prompt and rubric subsystem**  
   `src/lib/prompts.ts` holds the evaluation instructions used to steer the AI. Architecturally, this is important because the product’s behavior is defined less by code logic and more by the rubric: clarity, storytelling, and problem-solution fit.

7. **Evaluation orchestration**  
   `src/lib/evaluator.ts` likely coordinates the actual analysis call, assembling extracted deck text plus the prompt into a request for the LLM provider. The README indicates a **prompt-driven reasoning system** rather than a trained model, so this library is the core intelligence layer.

8. **Data flow through the system**  
   The likely flow is: **UI input → API route → PDF extraction (if needed) → evaluation prompt assembly → LLM call → structured report response → UI render**. This is the central architecture diagram path.

9. **Output shape**  
   The product returns a **decision-oriented investor report** rather than a generic summary. The key response categories are strengths, weaknesses, risks, and investor insights, aligned to the three evaluation dimensions described in the README.

10. **External dependency boundary**  
   The README mentions a **Groq API key**, so the evaluation layer depends on an external LLM service. That means the system’s core intelligence is network-bound and controlled by environment configuration rather than local ML inference.

11. **Deployment/runtime**  
   `netlify.toml` and `public/_redirects` indicate the app is intended to be deployed on **Netlify**. The repo is therefore a serverless-style Next.js deployment, where the API route is packaged as part of the hosting platform rather than a separate server process.

12. **Configuration and environment**  
   `.env.example` and the README’s `.env.local` instructions show that secrets are managed via environment variables, primarily for the Groq key. This is the main operational dependency needed to run the evaluation pipeline locally.

13. **Product constraint that affects architecture**  
   The README explicitly chooses **text-based analysis over multimodal understanding**. That design choice simplifies the architecture: there is no image, chart, or layout analysis pipeline, only extraction plus prompt-based reasoning.

14. **What to draw in an architecture diagram**  
   The main boxes should be: **Browser/UI**, **Next.js API route**, **PDF extraction**, **prompt/rubric assembly**, **Groq LLM service**, and **structured evaluation response**. The key boundary is between the app and the external model API; everything else is internal orchestration.

Main entry points: [`src/app/api/evaluate/route.ts`](https://github.com/youcef3939/evalia/blob/main/src/app/api/evaluate/route.ts) (Evaluate API), [`src/app/page.tsx`](https://github.com/youcef3939/evalia/blob/main/src/app/page.tsx) (Deck input), [`src/lib/evaluator.ts`](https://github.com/youcef3939/evalia/blob/main/src/lib/evaluator.ts) (Evaluator), [`README.md`](https://github.com/youcef3939/evalia/blob/main/README.md) (Product spec)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI"]
  node_page["Deck input<br/>Next.js page<br/>[page.tsx]"]
  node_layout["App shell<br/>Next.js layout<br/>[layout.tsx]"]
  node_styles["Global styles<br/>CSS<br/>[globals.css]"]
end

subgraph group_server["Server"]
  node_api["Evaluate API<br/>Route handler<br/>[route.ts]"]
  node_evaluator["Evaluator<br/>Orchestrator<br/>[evaluator.ts]"]
  node_extractor["PDF extractor<br/>Parser<br/>[pdfExtractor.ts]"]
  node_prompts["Prompts<br/>Rubric<br/>[prompts.ts]"]
  node_report["Report shape<br/>Structured output"]
end

subgraph group_platform["Platform"]
  node_groq(("Groq API<br/>LLM service"))
  node_env["Env vars<br/>Configuration<br/>[.env.example]"]
  node_next{{"Next runtime<br/>Framework runtime<br/>[next.config.ts]"}}
  node_netlify["Netlify deploy<br/>Hosting<br/>[netlify.toml]"]
  node_redirects["Redirects<br/>Hosting config"]
  node_readme["Product spec<br/>Docs<br/>[README.md]"]
  node_pkg["Package config<br/>Project config<br/>[package.json]"]
end

node_page -->|"submit deck"| node_api
node_layout -->|"renders"| node_page
node_styles -->|"styles"| node_page
node_api -->|"invoke"| node_evaluator
node_evaluator -->|"extract pdf"| node_extractor
node_evaluator -->|"assemble rubric"| node_prompts
node_evaluator -->|"call model"| node_groq
node_env -.->|"key"| node_groq
node_groq -->|"generate"| node_report
node_api -->|"respond"| node_report
node_readme -.->|"defines flow"| node_page
node_readme -.->|"pdf input"| node_extractor
node_readme -.->|"rubric"| node_prompts
node_pkg -->|"depends on"| node_next
node_next -->|"hosts"| node_api
node_next -->|"hosts"| node_page
node_netlify -->|"deploys"| node_api
node_redirects -->|"routes"| node_netlify

click node_page "https://github.com/youcef3939/evalia/blob/main/src/app/page.tsx"
click node_layout "https://github.com/youcef3939/evalia/blob/main/src/app/layout.tsx"
click node_styles "https://github.com/youcef3939/evalia/blob/main/src/app/globals.css"
click node_api "https://github.com/youcef3939/evalia/blob/main/src/app/api/evaluate/route.ts"
click node_evaluator "https://github.com/youcef3939/evalia/blob/main/src/lib/evaluator.ts"
click node_extractor "https://github.com/youcef3939/evalia/blob/main/src/lib/pdfExtractor.ts"
click node_prompts "https://github.com/youcef3939/evalia/blob/main/src/lib/prompts.ts"
click node_env "https://github.com/youcef3939/evalia/blob/main/.env.example"
click node_next "https://github.com/youcef3939/evalia/blob/main/next.config.ts"
click node_netlify "https://github.com/youcef3939/evalia/blob/main/netlify.toml"
click node_redirects "https://github.com/youcef3939/evalia/tree/main/public/_redirects"
click node_readme "https://github.com/youcef3939/evalia/blob/main/README.md"
click node_pkg "https://github.com/youcef3939/evalia/blob/main/package.json"

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_page,node_layout,node_styles toneBlue
class node_api,node_evaluator,node_extractor,node_prompts,node_report toneAmber
class node_groq,node_env,node_next,node_netlify,node_redirects,node_readme,node_pkg toneMint
```

## Components

### UI

Browser-facing app shell and evaluation screen

- [Deck input](https://github.com/youcef3939/evalia/blob/main/src/app/page.tsx): Next.js page · Primary user interface for submitting a pitch deck and viewing feedback · `src/app/page.tsx`
- [App shell](https://github.com/youcef3939/evalia/blob/main/src/app/layout.tsx): Next.js layout · Shared document structure for the application · `src/app/layout.tsx`
- [Global styles](https://github.com/youcef3939/evalia/blob/main/src/app/globals.css): CSS · Application-wide styling for the UI · `src/app/globals.css`

### Server

API route and evaluation pipeline

- [Evaluate API](https://github.com/youcef3939/evalia/blob/main/src/app/api/evaluate/route.ts): Route handler · Server boundary that receives deck input and returns an evaluation · `src/app/api/evaluate/route.ts`
- [Evaluator](https://github.com/youcef3939/evalia/blob/main/src/lib/evaluator.ts): Orchestrator · Coordinates extraction, prompt assembly, and model invocation · `src/lib/evaluator.ts`
- [PDF extractor](https://github.com/youcef3939/evalia/blob/main/src/lib/pdfExtractor.ts): Parser · Converts PDF decks into structured text for analysis · `src/lib/pdfExtractor.ts`
- [Prompts](https://github.com/youcef3939/evalia/blob/main/src/lib/prompts.ts): Rubric · Defines the evaluation instructions and scoring criteria · `src/lib/prompts.ts`
- **Report shape**: Structured output · Investor-style strengths, weaknesses, risks, and insights

### Platform

Deployment and external dependencies

- **Groq API**: LLM service · External model provider used for prompt-driven evaluation
- [Env vars](https://github.com/youcef3939/evalia/blob/main/.env.example): Configuration · Secrets and runtime configuration such as the Groq key · `.env.example`
- [Next runtime](https://github.com/youcef3939/evalia/blob/main/next.config.ts): Framework runtime · App Router runtime packaging UI and API in one app · `next.config.ts`
- [Netlify deploy](https://github.com/youcef3939/evalia/blob/main/netlify.toml): Hosting · Serverless deployment target for the Next.js application · `netlify.toml`
- [Redirects](https://github.com/youcef3939/evalia/tree/main/public/_redirects): Hosting config · Netlify redirect rules for routing the app · `public/_redirects`
- [Product spec](https://github.com/youcef3939/evalia/blob/main/README.md): Docs · Describes the text-based pitch deck evaluation flow and constraints · `README.md`
- [Package config](https://github.com/youcef3939/evalia/blob/main/package.json): Project config · Dependencies and scripts for the application · `package.json`

## Connections

- Deck input → Evaluate API: submit deck · Browser sends pitch deck content to the evaluation endpoint
- App shell → Deck input: renders · Shared app shell wraps the main page
- Global styles → Deck input: styles · Global CSS shapes the UI
- Evaluate API → Evaluator: invoke · API route delegates analysis work to the evaluator
- Evaluator → PDF extractor: extract pdf · Evaluator converts PDFs to text when needed
- Evaluator → Prompts: assemble rubric · Evaluator combines deck text with evaluation instructions
- Evaluator → Groq API: call model · Core analysis is performed by the external LLM service
- Env vars → Groq API: key · Environment configuration provides access credentials
- Groq API → Report shape: generate · Model returns structured investor-style feedback
- Evaluate API → Report shape: respond · Route returns the structured evaluation to the client
- Product spec → Deck input: defines flow · README describes the user-facing evaluation workflow
- Product spec → PDF extractor: pdf input · Documentation specifies PDF ingestion as a supported mode
- Product spec → Prompts: rubric · Documentation frames the rubric-driven analysis approach
- Package config → Next runtime: depends on · Project configuration anchors the Next.js app runtime
- Next runtime → Evaluate API: hosts · Framework runtime serves the API route within the app
- Next runtime → Deck input: hosts · Framework runtime serves the client-facing page
- Netlify deploy → Evaluate API: deploys · Netlify packages the route as part of the deployment
- Redirects → Netlify deploy: routes · Redirect rules support the hosted app routing