# kmrgautam18-alt/career-ops-v2 architecture

> Architecture diagram of the GitHub repository kmrgautam18-alt/career-ops-v2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kmrgautam18-alt/career-ops-v2
- Repository: https://github.com/kmrgautam18-alt/career-ops-v2

## Overview

1. **What this repo is**
   - This is a **Python backend service** for the Career-Ops v2 platform, plus a large documentation set that describes the intended system architecture.
   - The codebase is organized as a layered API backend: **API routes → services → repositories → database/models**.

2. **Top-level structure**
   - `backend/` contains the runnable application.
   - `tests/` contains API-level tests for auth, health, dashboard, resumes, and applications.
   - `docs/` is unusually important here: it contains architecture diagrams, API notes, database schema docs, and project vision material.
   - `archive/` holds legacy/demo code that is not part of the current main path.

3. **Application runtime boundary**
   - The backend is a **Python application** centered in `backend/app/main.py`.
   - `backend/app/api/router.py` and `backend/app/api/v1/*` define the HTTP surface.
   - The presence of `schemas/`, `services/`, `repositories/`, and `models/` strongly indicates a **FastAPI-style layered architecture** with request validation and dependency injection.

4. **API layer**
   - The API is versioned under `backend/app/api/v1/`.
   - Resource boundaries are explicit: `auth`, `users`, `jobs`, `resumes`, `applications`, `dashboard`, and `admin`.
   - This tells you the service is not a generic CRUD app; it is domain-shaped around job search, resume management, and application tracking.

5. **Business logic layer**
   - `backend/app/services/` is where use-case orchestration lives.
   - Separate services exist for each domain: `auth_service`, `user_service`, `job_service`, `resume_service`, `application_service`, `dashboard_service`, plus `resume_upload_service`.
   - The service layer is the main boundary where validation, authorization rules, and cross-entity workflows should be drawn in an architecture diagram.

6. **Persistence layer**
   - `backend/app/repositories/*_sa.py` indicates the current persistence pattern is **SQLAlchemy-based repositories**.
   - The main persisted entities are `User`, `Job`, `Resume`, and `Application` under `backend/app/models/`.
   - `backend/app/database/` contains DB setup, session management, dependency wiring, and initialization, so the app likely uses a relational database through a central session factory.

7. **Core domain concerns**
   - `backend/app/core/` contains shared enums/constants such as `roles`, `resume_status`, file constants, and configuration.
   - These are not just utilities; they define important domain boundaries such as authorization roles and resume lifecycle states.
   - `schemas/` provide the API contract layer for request/response validation and should be shown as separate from persistence models in any diagram.

8. **Authentication and authorization**
   - `backend/app/security/` contains JWT and password handling, plus security dependencies.
   - `backend/app/api/v1/auth.py` and `backend/app/security/dependencies.py` imply a token-based auth flow with role-aware access control.
   - `core/roles.py` and the `admin` route suggest RBAC is a first-class architectural concern.

9. **Resume/file handling path**
   - `backend/app/services/resume_upload_service.py`, `backend/app/utils/file_storage.py`, and `backend/app/utils/file_validator.py` show that resume upload is not purely database-driven.
   - There is a distinct file-storage boundary, with validation before persistence.
   - In the architecture diagram, this should appear as a side path alongside the database: uploaded files are validated, stored, and then associated with resume records.

10. **Cross-domain aggregation**
   - `dashboard_service` and `dashboard_repository_sa` imply the dashboard is an aggregation layer that reads across multiple domain entities.
   - This is likely a read-optimized use case that combines jobs, applications, resumes, and user state rather than owning its own primary data model.

11. **Error handling and operational concerns**
   - `backend/app/exceptions/` centralizes custom exceptions and handlers, including resume-specific errors.
   - `backend/app/utils/logger.py` suggests structured logging is part of the backend boundary.
   - These concerns are shared infrastructure, not business logic, and should be shown outside the domain services in a diagram.

12. **Testing and quality gates**
   - The test suite focuses on API behavior, which means the repo validates the system through its HTTP contracts.
   - `tests/conftest.py` and `tests/utils/auth_helper.py` indicate shared test fixtures and authenticated test flows.
   - This suggests integration-style coverage of the main request path rather than only isolated unit tests.

13. **Legacy and evolution**
   - `archive/legacy/` contains older repository implementations, including SQLite-based code, which indicates the project evolved from a simpler persistence setup to the current SQLAlchemy-based architecture.
   - `archive/demo/` contains a scraper demo, which is historical/supporting code rather than part of the core runtime.

14. **Documentation-driven architecture**
   - The `docs/architecture/`, `docs/diagrams/`, and `docs/database/` folders are central to understanding intended system boundaries.
   - The repository is explicitly documentation-first, and the docs reference system context, backend flow, auth/authorization flow, deployment, CI/CD, monitoring, and even AI matching workflows.
   - For an accurate architecture diagram, treat the docs as the source of intent and the `backend/` tree as the implemented subset currently present in this repository.

Main entry points: [`backend/app/services`](https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/services) (Services), [`backend/app/api/v1`](https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/api/v1) (v1 API), [`backend/app/repositories`](https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/repositories) (Repositories), [`backend/app/main.py`](https://github.com/kmrgautam18-alt/career-ops-v2/blob/main/backend/app/main.py) (App entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["App entry<br/>FastAPI app<br/>[main.py]"]
  node_router["API router<br/>HTTP routing<br/>[router.py]"]
  node_api_v1["v1 API<br/>versioned endpoints"]
  node_services["Services<br/>use-case layer"]
  node_repos[("Repositories<br/>data access")]
  node_models[("Models")]
  node_schemas["Schemas<br/>contracts"]
  node_security["Security<br/>authn/authz"]
  node_database[("Database<br/>session setup")]
  node_core{{"Core rules<br/>domain constants"}}
  node_exceptions["Exceptions<br/>error handling"]
  node_utils["File utils<br/>infrastructure"]
end

subgraph group_quality["Quality"]
  node_tests["API tests<br/>integration tests"]
end

subgraph group_intent["Docs"]
  node_docs_arch["Architecture docs<br/>design docs"]
  node_docs_db["DB docs<br/>schema docs"]
end

subgraph group_history["Archive"]
  node_legacy["Legacy code<br/>archived code"]
  node_demo["Demo scraper<br/>demo code"]
end

node_main -->|"wires routes"| node_router
node_router -->|"dispatches"| node_api_v1
node_api_v1 -->|"protects"| node_security
node_api_v1 -->|"calls"| node_services
node_services -->|"reads/writes"| node_repos
node_repos -->|"maps"| node_models
node_services -->|"validates"| node_schemas
node_api_v1 -->|"contracts"| node_schemas
node_services -->|"uses sessions"| node_database
node_services -->|"applies rules"| node_core
node_services -->|"raises/handles"| node_exceptions
node_services -->|"uploads files"| node_utils
node_api_v1 -.->|"verified by"| node_tests
node_docs_arch -.->|"describes"| node_main
node_docs_db -.->|"documents"| node_database
node_legacy -.->|"predecessor"| node_repos
node_demo -.->|"historical use"| node_utils

click node_main "https://github.com/kmrgautam18-alt/career-ops-v2/blob/main/backend/app/main.py"
click node_router "https://github.com/kmrgautam18-alt/career-ops-v2/blob/main/backend/app/api/router.py"
click node_api_v1 "https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/api/v1"
click node_services "https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/services"
click node_repos "https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/repositories"
click node_models "https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/models"
click node_schemas "https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/schemas"
click node_security "https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/security"
click node_database "https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/database"
click node_core "https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/core"
click node_exceptions "https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/exceptions"
click node_utils "https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/utils"
click node_tests "https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/tests"
click node_docs_arch "https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/docs/architecture"
click node_docs_db "https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/docs/database"
click node_legacy "https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/archive/legacy"
click node_demo "https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/archive/demo"

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_main,node_router,node_api_v1,node_services,node_repos,node_models,node_schemas,node_security,node_database,node_core,node_exceptions,node_utils toneBlue
class node_tests toneAmber
class node_docs_arch,node_docs_db toneMint
class node_legacy,node_demo toneRose
```

## Components

### Runtime

Runnable backend application and its layered internals

- [App entry](https://github.com/kmrgautam18-alt/career-ops-v2/blob/main/backend/app/main.py): FastAPI app · Application startup and runtime wiring · `backend/app/main.py`
- [API router](https://github.com/kmrgautam18-alt/career-ops-v2/blob/main/backend/app/api/router.py): HTTP routing · Top-level route registration and version dispatch · `backend/app/api/router.py`
- [v1 API](https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/api/v1): versioned endpoints · Resource endpoints for auth, users, jobs, resumes, applications, dashboard, and admin · `backend/app/api/v1`
- [Services](https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/services): use-case layer · Domain orchestration for auth, jobs, resumes, applications, users, and dashboard · `backend/app/services`
- [Repositories](https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/repositories): data access · SQLAlchemy repositories for persisted domain entities and dashboard reads · `backend/app/repositories`
- [Models](https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/models): domain models · Persistent entities for users, jobs, resumes, and applications · `backend/app/models`
- [Schemas](https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/schemas): contracts · Request and response validation models for the API · `backend/app/schemas`
- [Security](https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/security): authn/authz · JWT, password handling, and access-control dependencies · `backend/app/security`
- [Database](https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/database): session setup · DB configuration, session factory, dependencies, and initialization · `backend/app/database`
- [Core rules](https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/core): domain constants · Shared enums and configuration such as roles and resume status · `backend/app/core`
- [Exceptions](https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/exceptions): error handling · Custom exceptions and centralized handlers · `backend/app/exceptions`
- [File utils](https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/backend/app/utils): infrastructure · File validation, storage, and logging support · `backend/app/utils`

### Quality

Tests that exercise the HTTP contract

- [API tests](https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/tests): integration tests · HTTP-level tests for auth, health, dashboard, resumes, and applications · `tests`

### Docs

Architecture and domain documentation

- [Architecture docs](https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/docs/architecture): design docs · System architecture, diagrams, and backend flow documentation · `docs/architecture`
- [DB docs](https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/docs/database): schema docs · Database schema and data model documentation · `docs/database`

### Archive

Legacy and demo code kept outside the main runtime

- [Legacy code](https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/archive/legacy): archived code · Older repository implementations retained for reference · `archive/legacy`
- [Demo scraper](https://github.com/kmrgautam18-alt/career-ops-v2/tree/main/archive/demo): demo code · Historical scraping demo not used by the main runtime · `archive/demo`

## Connections

- App entry → API router: wires routes · Application startup mounts the HTTP router
- API router → v1 API: dispatches · Top-level router exposes the versioned API surface
- v1 API → Security: protects · Auth, JWT, and dependency guards secure endpoints
- v1 API → Services: calls · Endpoints delegate domain work to services
- Services → Repositories: reads/writes · Use cases persist and query data through repositories
- Repositories → Models: maps · Repositories operate on SQLAlchemy domain models
- Services → Schemas: validates · Service inputs and outputs are shaped by API schemas
- v1 API → Schemas: contracts · Routes expose request and response models
- Services → Database: uses sessions · Repositories and services depend on shared DB wiring
- Services → Core rules: applies rules · Business logic uses roles, statuses, and config constants
- Services → Exceptions: raises/handles · Domain failures are normalized through custom exceptions
- Services → File utils: uploads files · Resume workflows validate and store files before persistence
- v1 API → API tests: verified by · API behavior is exercised through integration tests
- Architecture docs → App entry: describes · Architecture docs define the intended backend structure
- DB docs → Database: documents · Schema documentation explains persistence design
- Legacy code → Repositories: predecessor · Legacy repository implementations show the earlier persistence approach
- Demo scraper → File utils: historical use · Demo scraper is supporting historical code outside the core path
