# warmarth/folio architecture

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

- Interactive diagram: https://gitdiagram.com/warmarth/folio
- Repository: https://github.com/warmarth/folio

## Overview

Folio is a Flask API for a developer-learning platform. Learners and mentors register or log in, receive JWTs, create or browse profiles, and manage mentorship requests; active relationships expose mentor-created exercises to learners. Learners submit answers for AI evaluation, with successful work awarding XP. Profile image upload is an optional R2 integration. The graph follows documented routes and sampled call ownership; unsampled route wiring and model details are represented only where the README supports the capability.

Main entry points: [`backend/app/__init__.py`](https://github.com/warmarth/folio/blob/main/backend/app/__init__.py) (Flask app), [`backend/app/database.py`](https://github.com/warmarth/folio/blob/main/backend/app/database.py) (SQLite database), [`backend/app/routes/routes.py`](https://github.com/warmarth/folio/blob/main/backend/app/routes/routes.py) (Profile routes), [`backend/app/services/submit_exercise_service.py`](https://github.com/warmarth/folio/blob/main/backend/app/services/submit_exercise_service.py) (Submission service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API entrypoints"]
  node_app["Flask app<br/>[__init__.py]"]
end

subgraph group_identity["Identity and profiles"]
  node_auth["Authentication routes<br/>[routes.py]"]
  node_profile_routes["Profile routes<br/>[routes.py]"]
  node_user_profiles["Users and profiles<br/>[models.py]"]
  node_r2_upload["Image upload helper<br/>[r2.py]"]
end

subgraph group_mentorship["Mentorship"]
  node_mentor_routes["Mentorship routes<br/>[mentorlearner.py]"]
  node_relationship_service["Relationship service"]
  node_relationship_repo["Relationship repository"]
end

subgraph group_learning["Exercises and evaluation"]
  node_exercise_routes["Exercise routes<br/>[exercise_route.py]"]
  node_submission_routes["Submission routes<br/>[submitted.py]"]
  node_submission_service["Submission service"]
  node_submission_repo["Submission repository"]
  node_evaluator["AI evaluator<br/>[ai_evaluator.py]"]
end

subgraph group_persistence["Persistence and uploads"]
  node_models["Domain models<br/>[models.py]"]
  node_database[("SQLite database<br/>[database.py]")]
end

node_client(("API client"))
node_r2[("Cloudflare R2")]
node_groq(("Groq"))

node_client -->|"sends requests"| node_app
node_app -->|"registers routes"| node_auth
node_app -->|"registers routes"| node_profile_routes
node_app -->|"registers routes"| node_mentor_routes
node_app -->|"registers routes"| node_exercise_routes
node_app -->|"registers routes"| node_submission_routes
node_auth -->|"queries users"| node_user_profiles
node_auth -->|"writes accounts"| node_database
node_profile_routes -->|"queries profiles"| node_user_profiles
node_profile_routes -->|"writes profiles"| node_database
node_profile_routes -.->|"uploads image"| node_r2_upload
node_r2_upload -.->|"stores image"| node_r2
node_mentor_routes -->|"manages requests"| node_relationship_service
node_relationship_service -->|"reads and updates"| node_relationship_repo
node_relationship_repo -->|"persists relationships"| node_database
node_exercise_routes -->|"queries and writes"| node_database
node_submission_routes -->|"submits answer"| node_submission_service
node_submission_service -->|"reads and saves"| node_submission_repo
node_submission_service -->|"evaluates answer"| node_evaluator
node_evaluator -->|"requests evaluation"| node_groq
node_submission_service -->|"reads exercise and awards XP"| node_database
node_submission_repo -->|"persists submissions"| node_database
node_app -->|"initializes storage"| node_database

click node_app "https://github.com/warmarth/folio/blob/main/backend/app/__init__.py"
click node_auth "https://github.com/warmarth/folio/blob/main/backend/app/auth/routes.py"
click node_profile_routes "https://github.com/warmarth/folio/blob/main/backend/app/routes/routes.py"
click node_user_profiles "https://github.com/warmarth/folio/blob/main/backend/app/models.py"
click node_r2_upload "https://github.com/warmarth/folio/blob/main/backend/app/storage/r2.py"
click node_mentor_routes "https://github.com/warmarth/folio/blob/main/backend/app/routes/mentorlearner.py"
click node_relationship_service "https://github.com/warmarth/folio/blob/main/backend/app/services/relationshipservices.py"
click node_relationship_repo "https://github.com/warmarth/folio/blob/main/backend/app/repository/mentorlearnerrepo.py"
click node_exercise_routes "https://github.com/warmarth/folio/blob/main/backend/app/routes/exercise_route.py"
click node_submission_routes "https://github.com/warmarth/folio/blob/main/backend/app/routes/submitted.py"
click node_submission_service "https://github.com/warmarth/folio/blob/main/backend/app/services/submit_exercise_service.py"
click node_submission_repo "https://github.com/warmarth/folio/blob/main/backend/app/repository/exercise_submission.py"
click node_evaluator "https://github.com/warmarth/folio/blob/main/backend/app/evaluator/ai_evaluator.py"
click node_models "https://github.com/warmarth/folio/blob/main/backend/app/models.py"
click node_database "https://github.com/warmarth/folio/blob/main/backend/app/database.py"

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_app,node_client toneBlue
class node_auth,node_profile_routes,node_user_profiles,node_r2_upload,node_r2 toneAmber
class node_mentor_routes,node_relationship_service,node_relationship_repo toneMint
class node_exercise_routes,node_submission_routes,node_submission_service,node_submission_repo,node_evaluator toneRose
class node_models,node_database,node_groq toneIndigo
```

## Components

### API entrypoints

- [Flask app](https://github.com/warmarth/folio/blob/main/backend/app/__init__.py): `backend/app/__init__.py`

### Identity and profiles

- [Authentication routes](https://github.com/warmarth/folio/blob/main/backend/app/auth/routes.py): `backend/app/auth/routes.py`
- [Profile routes](https://github.com/warmarth/folio/blob/main/backend/app/routes/routes.py): `backend/app/routes/routes.py`
- [Users and profiles](https://github.com/warmarth/folio/blob/main/backend/app/models.py): `backend/app/models.py`
- [Image upload helper](https://github.com/warmarth/folio/blob/main/backend/app/storage/r2.py): `backend/app/storage/r2.py`

### Mentorship

- [Mentorship routes](https://github.com/warmarth/folio/blob/main/backend/app/routes/mentorlearner.py): `backend/app/routes/mentorlearner.py`
- [Relationship service](https://github.com/warmarth/folio/blob/main/backend/app/services/relationshipservices.py): `backend/app/services/relationshipservices.py`
- [Relationship repository](https://github.com/warmarth/folio/blob/main/backend/app/repository/mentorlearnerrepo.py): `backend/app/repository/mentorlearnerrepo.py`

### Exercises and evaluation

- [Exercise routes](https://github.com/warmarth/folio/blob/main/backend/app/routes/exercise_route.py): `backend/app/routes/exercise_route.py`
- [Submission routes](https://github.com/warmarth/folio/blob/main/backend/app/routes/submitted.py): `backend/app/routes/submitted.py`
- [Submission service](https://github.com/warmarth/folio/blob/main/backend/app/services/submit_exercise_service.py): `backend/app/services/submit_exercise_service.py`
- [Submission repository](https://github.com/warmarth/folio/blob/main/backend/app/repository/exercise_submission.py): `backend/app/repository/exercise_submission.py`
- [AI evaluator](https://github.com/warmarth/folio/blob/main/backend/app/evaluator/ai_evaluator.py): `backend/app/evaluator/ai_evaluator.py`

### Persistence and uploads

- [Domain models](https://github.com/warmarth/folio/blob/main/backend/app/models.py): `backend/app/models.py`
- [SQLite database](https://github.com/warmarth/folio/blob/main/backend/app/database.py): `backend/app/database.py`

### Other components

- **API client**
- **Cloudflare R2**
- **Groq**

## Connections

- API client → Flask app: sends requests
- Flask app → Authentication routes: registers routes
- Flask app → Profile routes: registers routes
- Flask app → Mentorship routes: registers routes
- Flask app → Exercise routes: registers routes
- Flask app → Submission routes: registers routes
- Authentication routes → Users and profiles: queries users
- Authentication routes → SQLite database: writes accounts
- Profile routes → Users and profiles: queries profiles
- Profile routes → SQLite database: writes profiles
- Profile routes → Image upload helper: uploads image
- Image upload helper → Cloudflare R2: stores image
- Mentorship routes → Relationship service: manages requests
- Relationship service → Relationship repository: reads and updates
- Relationship repository → SQLite database: persists relationships
- Exercise routes → SQLite database: queries and writes
- Submission routes → Submission service: submits answer
- Submission service → Submission repository: reads and saves
- Submission service → AI evaluator: evaluates answer
- AI evaluator → Groq: requests evaluation
- Submission service → SQLite database: reads exercise and awards XP
- Submission repository → SQLite database: persists submissions
- Flask app → SQLite database: initializes storage