How kmrgautam18-alt/career-ops-v2 works
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: services Services · v1 v1 API · repositories Repositories · main.py App entry
Components 17
Runtime
Runnable backend application and its layered internals
- App entry · Application startup and runtime wiring
backend/app/main.py - API router · Top-level route registration and version dispatch
backend/app/api/router.py - v1 API · Resource endpoints for auth, users, jobs, resumes, applications, dashboard, and admin
backend/app/api/v1 - Services · Domain orchestration for auth, jobs, resumes, applications, users, and dashboard
backend/app/services - Repositories · SQLAlchemy repositories for persisted domain entities and dashboard reads
backend/app/repositories - Models · Persistent entities for users, jobs, resumes, and applications
backend/app/models - Schemas · Request and response validation models for the API
backend/app/schemas - Security · JWT, password handling, and access-control dependencies
backend/app/security - Database · DB configuration, session factory, dependencies, and initialization
backend/app/database - Core rules · Shared enums and configuration such as roles and resume status
backend/app/core - Exceptions · Custom exceptions and centralized handlers
backend/app/exceptions - File utils · File validation, storage, and logging support
backend/app/utils
Quality
Tests that exercise the HTTP contract
- API tests · HTTP-level tests for auth, health, dashboard, resumes, and applications
tests
Docs
Architecture and domain documentation
- Architecture docs · System architecture, diagrams, and backend flow documentation
docs/architecture - DB docs · Database schema and data model documentation
docs/database
Archive
Legacy and demo code kept outside the main runtime
- Legacy code · Older repository implementations retained for reference
archive/legacy - Demo scraper · Historical scraping demo not used by the main runtime
archive/demo
Connections 17
- 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