# vaaman5-web/ace-platform-db architecture

> Architecture diagram of the GitHub repository vaaman5-web/ace-platform-db, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vaaman5-web/ace-platform-db
- Repository: https://github.com/vaaman5-web/ace-platform-db

## Overview

ACE is an education and placement-readiness platform. A learner uses the web interface to register, explore companies, assess skills and quiz readiness, then review preparation plans and reports. The backend exposes these capabilities through Express routes and uses PostgreSQL for application data; the sampled matching service queries that database, while the scoring engine computes readiness results. AI generation can use external language-model providers. Several route implementations were not sampled, so uncertain route-to-service and report-generation links are omitted.

Main entry points: [`server.js`](https://github.com/vaaman5-web/ace-platform-db/blob/main/server.js) (Express server), [`public/js/api.js`](https://github.com/vaaman5-web/ace-platform-db/blob/main/public/js/api.js) (API client), [`config/database.js`](https://github.com/vaaman5-web/ace-platform-db/blob/main/config/database.js) (PostgreSQL), [`services/aiService.js`](https://github.com/vaaman5-web/ace-platform-db/blob/main/services/aiService.js) (AI generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Learner interface"]
  node_web["Web interface<br/>[index.html]"]
  node_webapi["API client<br/>[api.js]"]
  node_companydata["Company data UI<br/>[companies-data.js]"]
  node_quizui["Adaptive quiz UI<br/>[quiz-ai.js]"]
end

subgraph group_api["API and identity"]
  node_server["Express server<br/>[server.js]"]
  node_auth["Authentication routes<br/>[auth.js]"]
  node_companies["Company routes<br/>[companies.js]"]
  node_analysis["Analysis routes<br/>[analysis.js]"]
  node_quiz["Quiz routes<br/>[quiz.js]"]
  node_reports["Report routes<br/>[reports.js]"]
  node_ai["AI routes<br/>[ai.js]"]
  node_admin["Admin routes<br/>[admin.js]"]
end

subgraph group_learning["Readiness and preparation"]
  node_scoring["Readiness scoring<br/>[scoringEngine.js]"]
  node_matching["Company matching<br/>[matchingService.js]"]
  node_ai_service["AI generation<br/>[aiService.js]"]
  node_pdf["PDF generation<br/>[pdfGenerator.js]"]
end

subgraph group_data["Application data"]
  node_database[("PostgreSQL<br/>[database.js]")]
end

subgraph group_integrations["External providers"]
  node_openai["OpenAI"]
  node_gemini["Gemini"]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_web
node_web -->|"calls"| node_webapi
node_webapi -->|"sends requests"| node_server
node_companydata -->|"uses"| node_webapi
node_quizui -->|"requests quizzes"| node_ai
node_server -->|"mounts"| node_auth
node_server -->|"mounts"| node_companies
node_server -->|"mounts"| node_analysis
node_server -->|"mounts"| node_quiz
node_server -->|"mounts"| node_reports
node_server -->|"mounts"| node_ai
node_server -->|"mounts"| node_admin
node_auth -->|"queries"| node_database
node_server -->|"checks health"| node_database
node_matching -->|"queries"| node_database
node_ai_service -.->|"calls optionally"| node_openai
node_ai_service -.->|"calls optionally"| node_gemini

click node_web "https://github.com/vaaman5-web/ace-platform-db/blob/main/public/index.html"
click node_webapi "https://github.com/vaaman5-web/ace-platform-db/blob/main/public/js/api.js"
click node_companydata "https://github.com/vaaman5-web/ace-platform-db/blob/main/public/js/companies-data.js"
click node_quizui "https://github.com/vaaman5-web/ace-platform-db/blob/main/public/js/quiz-ai.js"
click node_server "https://github.com/vaaman5-web/ace-platform-db/blob/main/server.js"
click node_auth "https://github.com/vaaman5-web/ace-platform-db/blob/main/routes/auth.js"
click node_companies "https://github.com/vaaman5-web/ace-platform-db/blob/main/routes/companies.js"
click node_analysis "https://github.com/vaaman5-web/ace-platform-db/blob/main/routes/analysis.js"
click node_quiz "https://github.com/vaaman5-web/ace-platform-db/blob/main/routes/quiz.js"
click node_reports "https://github.com/vaaman5-web/ace-platform-db/blob/main/routes/reports.js"
click node_ai "https://github.com/vaaman5-web/ace-platform-db/blob/main/routes/ai.js"
click node_admin "https://github.com/vaaman5-web/ace-platform-db/blob/main/routes/admin.js"
click node_scoring "https://github.com/vaaman5-web/ace-platform-db/blob/main/services/scoringEngine.js"
click node_matching "https://github.com/vaaman5-web/ace-platform-db/blob/main/services/matchingService.js"
click node_ai_service "https://github.com/vaaman5-web/ace-platform-db/blob/main/services/aiService.js"
click node_pdf "https://github.com/vaaman5-web/ace-platform-db/blob/main/services/pdfGenerator.js"
click node_database "https://github.com/vaaman5-web/ace-platform-db/blob/main/config/database.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_web,node_webapi,node_companydata,node_quizui toneBlue
class node_server,node_auth,node_companies,node_analysis,node_quiz,node_reports,node_ai,node_admin toneAmber
class node_scoring,node_matching,node_ai_service,node_pdf toneMint
class node_database toneRose
class node_openai,node_gemini,node_learner toneIndigo
```

## Components

### Learner interface

- [Web interface](https://github.com/vaaman5-web/ace-platform-db/blob/main/public/index.html): `public/index.html`
- [API client](https://github.com/vaaman5-web/ace-platform-db/blob/main/public/js/api.js): `public/js/api.js`
- [Company data UI](https://github.com/vaaman5-web/ace-platform-db/blob/main/public/js/companies-data.js): `public/js/companies-data.js`
- [Adaptive quiz UI](https://github.com/vaaman5-web/ace-platform-db/blob/main/public/js/quiz-ai.js): `public/js/quiz-ai.js`

### API and identity

- [Express server](https://github.com/vaaman5-web/ace-platform-db/blob/main/server.js): `server.js`
- [Authentication routes](https://github.com/vaaman5-web/ace-platform-db/blob/main/routes/auth.js): `routes/auth.js`
- [Company routes](https://github.com/vaaman5-web/ace-platform-db/blob/main/routes/companies.js): `routes/companies.js`
- [Analysis routes](https://github.com/vaaman5-web/ace-platform-db/blob/main/routes/analysis.js): `routes/analysis.js`
- [Quiz routes](https://github.com/vaaman5-web/ace-platform-db/blob/main/routes/quiz.js): `routes/quiz.js`
- [Report routes](https://github.com/vaaman5-web/ace-platform-db/blob/main/routes/reports.js): `routes/reports.js`
- [AI routes](https://github.com/vaaman5-web/ace-platform-db/blob/main/routes/ai.js): `routes/ai.js`
- [Admin routes](https://github.com/vaaman5-web/ace-platform-db/blob/main/routes/admin.js): `routes/admin.js`

### Readiness and preparation

- [Readiness scoring](https://github.com/vaaman5-web/ace-platform-db/blob/main/services/scoringEngine.js): `services/scoringEngine.js`
- [Company matching](https://github.com/vaaman5-web/ace-platform-db/blob/main/services/matchingService.js): `services/matchingService.js`
- [AI generation](https://github.com/vaaman5-web/ace-platform-db/blob/main/services/aiService.js): `services/aiService.js`
- [PDF generation](https://github.com/vaaman5-web/ace-platform-db/blob/main/services/pdfGenerator.js): `services/pdfGenerator.js`

### Application data

- [PostgreSQL](https://github.com/vaaman5-web/ace-platform-db/blob/main/config/database.js): `config/database.js`

### External providers

- **OpenAI**
- **Gemini**

### Other components

- **Learner**

## Connections

- Learner → Web interface: uses
- Web interface → API client: calls
- API client → Express server: sends requests
- Company data UI → API client: uses
- Adaptive quiz UI → AI routes: requests quizzes
- Express server → Authentication routes: mounts
- Express server → Company routes: mounts
- Express server → Analysis routes: mounts
- Express server → Quiz routes: mounts
- Express server → Report routes: mounts
- Express server → AI routes: mounts
- Express server → Admin routes: mounts
- Authentication routes → PostgreSQL: queries
- Express server → PostgreSQL: checks health
- Company matching → PostgreSQL: queries
- AI generation → OpenAI: calls optionally
- AI generation → Gemini: calls optionally