# mdasar2927/employ-ai architecture

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

- Interactive diagram: https://gitdiagram.com/mdasar2927/employ-ai
- Repository: https://github.com/mdasar2927/employ-ai

## Overview

#### Purpose and entry points
Employ-AI is a career-support application organized as static, task-specific frontend screens plus a Python backend API. User workflows cover profile creation, resume handling, skill analysis/gaps, internship recommendations, learning, and reporting.

Primary entry points:
- Frontend landing screen: `1. main screen/main_screen.html`
- Backend application bootstrap: `backend/app/main.py`
- Shared browser API/auth integration: `shared/api.js`, `shared/auth.js`

#### Frontend workflow surfaces
The frontend is split into independent HTML screens rather than a single bundled web application. Each screen represents a major user-facing stage and likely calls the common shared API/auth layer.

Core screens:
- Profile: `2. profile/profile.html`
- Resume: `3. resume/resume.html`
- Skill analysis and gap views: `4. skill analysis/skill_analysis.html`, `6. skill gap/skill_gap.html`
- Internship recommendation: `5.internship recommendation/internship_recc.html`
- Learning and report outputs: `7. learner/learner.html`, `8. report/report.html`

`INTEGRATION_MAP.md` is the likely contract map between these screens and backend endpoints.

#### API boundary and request organization
The backend is structured around routers, schemas, repositories, and services. Routers expose feature APIs; schemas define request/response models; repositories isolate persistence access; services hold analysis and generation logic.

Feature API modules:
- `backend/app/routers/profile.py`
- `backend/app/routers/resume.py`
- `backend/app/routers/matching.py`
- `backend/app/routers/internships.py`
- `backend/app/routers/learning.py`
- `backend/app/routers/reports.py`

Corresponding typed contracts live in `backend/app/schemas/`, including `backend/app/schemas/profile.py`, `backend/app/schemas/resume.py`, and `backend/app/schemas/matching.py`.

#### Career analysis pipeline
The principal control flow is profile/resume input into analysis, matching, learning-roadmap, and report outputs.

Key processing components:
- Resume parsing: `backend/app/services/resume_parser.py`
- AI-backed analysis: `backend/app/services/ai_analyzer.py`
- Candidate-to-opportunity matching: `backend/app/services/matching_engine.py`
- Learning/roadmap generation: `backend/app/services/roadmap_generator.py`

Likely flow: the resume and profile APIs persist user inputs, parsing/AI analysis derives skills or candidate attributes, matching evaluates internship fit, roadmap generation converts gaps into learning recommendations, and reporting aggregates these results.

#### Persistence and security boundary
Supabase is the explicit database integration and is accessed through a dedicated database module:
- `backend/app/db/supabase.py`
- `backend/schema.sql`
- `backend/migrations/001_rls_security.sql`

Repositories form the persistence boundary for domain data:
- `backend/app/repositories/profiles.py`
- `backend/app/repositories/resumes.py`
- `backend/app/repositories/matches.py`
- `backend/app/repositories/internships.py`
- `backend/app/repositories/learning.py`
- `backend/app/repositories/reports.py`

Row-level security is architecturally material because `backend/migrations/001_rls_security.sql` indicates database-enforced tenant/user access controls. Frontend authentication handling is centralized in `shared/auth.js`.

#### Runtime and configuration
The backend is a Python service with dependency and configuration layers:
- `backend/requirements.txt`
- `backend/app/core/config.py`
- `backend/app/api/dependencies.py`
- `.env.example`

Environment configuration should supply Supabase connectivity and any external AI-provider credentials consumed by `backend/app/services/ai_analyzer.py`. The frontend remains static HTML/JavaScript, using `shared/api.js` as its backend-service boundary.

Main entry points: [`shared/api.js`](https://github.com/mdasar2927/employ-ai/blob/main/shared/api.js) (Shared API & auth), [`backend/app/repositories/profiles.py`](https://github.com/mdasar2927/employ-ai/blob/main/backend/app/repositories/profiles.py) (Domain repositories), [`backend/app/routers/profile.py`](https://github.com/mdasar2927/employ-ai/blob/main/backend/app/routers/profile.py) (Feature routers), [`backend/app/services/ai_analyzer.py`](https://github.com/mdasar2927/employ-ai/blob/main/backend/app/services/ai_analyzer.py) (AI skill analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Static Frontend"]
  node_landing["Landing screen<br/>HTML entry<br/>[main_screen.html]"]
  node_profile_screen["Profile screen<br/>HTML screen<br/>[profile.html]"]
  node_resume_screen["Resume screen<br/>HTML screen<br/>[resume.html]"]
  node_career_screens["Analysis, recommendations &amp; outputs<br/>HTML screens"]
  node_browser_integration["Shared API &amp; auth<br/>browser integration<br/>[api.js]"]
end

subgraph group_api["Python API"]
  node_app_bootstrap{{"API application<br/>Python bootstrap<br/>[main.py]"}}
  node_feature_routers["Feature routers<br/>API routers<br/>[profile.py]"]
  node_schemas["Typed contracts<br/>schemas<br/>[profile.py]"]
end

subgraph group_pipeline["Career Intelligence"]
  node_resume_parser["Resume parser<br/>[resume_parser.py]"]
  node_ai_analyzer{{"AI skill analysis<br/>AI service<br/>[ai_analyzer.py]"}}
  node_matching_engine["Opportunity matching<br/>[matching_engine.py]"]
  node_roadmap_generator["Learning roadmap generation"]
end

subgraph group_data["Data &amp; Security"]
  node_repositories["Domain repositories<br/>persistence layer<br/>[profiles.py]"]
  node_supabase[("Supabase<br/>database integration<br/>[supabase.py]")]
  node_rls["Row-level security<br/>database policy"]
end

node_integration_map["Integration contract map<br/>documentation<br/>[INTEGRATION_MAP.md]"]

node_landing -->|"starts workflow"| node_profile_screen
node_profile_screen -->|"uses"| node_browser_integration
node_resume_screen -->|"uses"| node_browser_integration
node_career_screens -->|"uses"| node_browser_integration
node_browser_integration -->|"authenticated API requests"| node_app_bootstrap
node_integration_map -.->|"documents contracts"| node_browser_integration
node_app_bootstrap -->|"mounts"| node_feature_routers
node_feature_routers -->|"validates with"| node_schemas
node_feature_routers -->|"resume intake"| node_resume_parser
node_resume_parser -->|"parsed resume"| node_ai_analyzer
node_ai_analyzer -->|"skills and attributes"| node_matching_engine
node_matching_engine -->|"skill gaps"| node_roadmap_generator
node_feature_routers -->|"persists and retrieves"| node_repositories
node_ai_analyzer -->|"stores analysis"| node_repositories
node_matching_engine -->|"stores matches"| node_repositories
node_roadmap_generator -->|"stores learning plans"| node_repositories
node_repositories -->|"data access"| node_supabase
node_rls -->|"enforces access policy"| node_supabase

click node_landing "https://github.com/mdasar2927/employ-ai/blob/main/1.%20main%20screen/main_screen.html"
click node_profile_screen "https://github.com/mdasar2927/employ-ai/blob/main/2.%20profile/profile.html"
click node_resume_screen "https://github.com/mdasar2927/employ-ai/blob/main/3.%20resume/resume.html"
click node_browser_integration "https://github.com/mdasar2927/employ-ai/blob/main/shared/api.js"
click node_app_bootstrap "https://github.com/mdasar2927/employ-ai/blob/main/backend/app/main.py"
click node_feature_routers "https://github.com/mdasar2927/employ-ai/blob/main/backend/app/routers/profile.py"
click node_schemas "https://github.com/mdasar2927/employ-ai/blob/main/backend/app/schemas/profile.py"
click node_resume_parser "https://github.com/mdasar2927/employ-ai/blob/main/backend/app/services/resume_parser.py"
click node_ai_analyzer "https://github.com/mdasar2927/employ-ai/blob/main/backend/app/services/ai_analyzer.py"
click node_matching_engine "https://github.com/mdasar2927/employ-ai/blob/main/backend/app/services/matching_engine.py"
click node_roadmap_generator "https://github.com/mdasar2927/employ-ai/blob/main/backend/app/services/roadmap_generator.py"
click node_repositories "https://github.com/mdasar2927/employ-ai/blob/main/backend/app/repositories/profiles.py"
click node_supabase "https://github.com/mdasar2927/employ-ai/blob/main/backend/app/db/supabase.py"
click node_rls "https://github.com/mdasar2927/employ-ai/blob/main/backend/migrations/001_rls_security.sql"
click node_integration_map "https://github.com/mdasar2927/employ-ai/blob/main/INTEGRATION_MAP.md"

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_landing,node_profile_screen,node_resume_screen,node_career_screens,node_browser_integration toneBlue
class node_app_bootstrap,node_feature_routers,node_schemas toneAmber
class node_resume_parser,node_ai_analyzer,node_matching_engine,node_roadmap_generator toneMint
class node_repositories,node_supabase,node_rls toneRose
class node_integration_map toneNeutral
```

## Components

### Static Frontend

Independent HTML workflow screens share browser integration.

- [Landing screen](https://github.com/mdasar2927/employ-ai/blob/main/1.%20main%20screen/main_screen.html): HTML entry · `1. main screen/main_screen.html`
- [Profile screen](https://github.com/mdasar2927/employ-ai/blob/main/2.%20profile/profile.html): HTML screen · `2. profile/profile.html`
- [Resume screen](https://github.com/mdasar2927/employ-ai/blob/main/3.%20resume/resume.html): HTML screen · `3. resume/resume.html`
- **Analysis, recommendations & outputs**: HTML screens · Skill analysis, gaps, internships, learning, and reports.
- [Shared API & auth](https://github.com/mdasar2927/employ-ai/blob/main/shared/api.js): browser integration · Centralizes backend calls and frontend authentication. · `shared/api.js`

### Python API

Feature routers and typed contracts expose career workflows.

- [API application](https://github.com/mdasar2927/employ-ai/blob/main/backend/app/main.py): Python bootstrap · `backend/app/main.py`
- [Feature routers](https://github.com/mdasar2927/employ-ai/blob/main/backend/app/routers/profile.py): API routers · Profile, resume, matching, internships, learning, and reports endpoints. · `backend/app/routers/profile.py`
- [Typed contracts](https://github.com/mdasar2927/employ-ai/blob/main/backend/app/schemas/profile.py): schemas · Request and response models shared across feature APIs. · `backend/app/schemas/profile.py`

### Career Intelligence

Services derive skills, matches, learning plans, and reports.

- [Resume parser](https://github.com/mdasar2927/employ-ai/blob/main/backend/app/services/resume_parser.py): service · `backend/app/services/resume_parser.py`
- [AI skill analysis](https://github.com/mdasar2927/employ-ai/blob/main/backend/app/services/ai_analyzer.py): AI service · Derives skills and candidate attributes using configured AI providers. · `backend/app/services/ai_analyzer.py`
- [Opportunity matching](https://github.com/mdasar2927/employ-ai/blob/main/backend/app/services/matching_engine.py): service · `backend/app/services/matching_engine.py`
- [Learning roadmap generation](https://github.com/mdasar2927/employ-ai/blob/main/backend/app/services/roadmap_generator.py): service · `backend/app/services/roadmap_generator.py`

### Data & Security

Repositories mediate Supabase persistence under row-level security.

- [Domain repositories](https://github.com/mdasar2927/employ-ai/blob/main/backend/app/repositories/profiles.py): persistence layer · Profile, resume, match, internship, learning, and report data access. · `backend/app/repositories/profiles.py`
- [Supabase](https://github.com/mdasar2927/employ-ai/blob/main/backend/app/db/supabase.py): database integration · `backend/app/db/supabase.py`
- [Row-level security](https://github.com/mdasar2927/employ-ai/blob/main/backend/migrations/001_rls_security.sql): database policy · Database-enforced user and tenant access controls. · `backend/migrations/001_rls_security.sql`

### Other components

- [Integration contract map](https://github.com/mdasar2927/employ-ai/blob/main/INTEGRATION_MAP.md): documentation · Maps frontend screens to backend endpoint contracts. · `INTEGRATION_MAP.md`

## Connections

- Landing screen → Profile screen: starts workflow
- Profile screen → Shared API & auth: uses
- Resume screen → Shared API & auth: uses
- Analysis, recommendations & outputs → Shared API & auth: uses
- Shared API & auth → API application: authenticated API requests
- Integration contract map → Shared API & auth: documents contracts
- API application → Feature routers: mounts
- Feature routers → Typed contracts: validates with
- Feature routers → Resume parser: resume intake
- Resume parser → AI skill analysis: parsed resume
- AI skill analysis → Opportunity matching: skills and attributes
- Opportunity matching → Learning roadmap generation: skill gaps
- Feature routers → Domain repositories: persists and retrieves
- AI skill analysis → Domain repositories: stores analysis
- Opportunity matching → Domain repositories: stores matches
- Learning roadmap generation → Domain repositories: stores learning plans
- Domain repositories → Supabase: data access
- Row-level security → Supabase: enforces access policy