# arunkoo/jobvyn architecture

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

- Interactive diagram: https://gitdiagram.com/arunkoo/jobvyn
- Repository: https://github.com/arunkoo/jobvyn

## Overview

1. **Repository shape**
   - This is a monorepo with a **Next.js frontend** and a **Node.js/TypeScript backend split into microservices**.
   - The backend is not a single API: it has a **gateway** plus domain services for **auth, user, job, payment**, and an async **utils** service.

2. **Primary request path**
   - Most client traffic starts in the **frontend** and then goes to the **API Gateway**.
   - The gateway is the system’s edge boundary: it decides which backend service handles a request based on URL prefix, and forwards the request onward.

3. **Gateway responsibilities**
   - The gateway centralizes cross-cutting concerns: **routing, JWT validation, rate limiting, request IDs, logging, and error shaping**.
   - It uses **Redis** for rate limiting and adds traceability headers such as a unique request ID.
   - Public routes are explicitly exempted from auth checks, while most other routes are protected before proxying.

4. **Frontend architecture**
   - The frontend is a **Next.js App Router** application with route groups for **auth, jobs, account, company, subscribe, reset, and payment success**.
   - The UI is composed of reusable components and a shared app context, suggesting a client that consumes backend APIs rather than owning business logic.
   - Frontend screens map closely to the platform’s domain flows: browsing jobs, account management, registration/login, subscription, and password reset.

5. **Auth service**
   - The auth service owns **registration, login, JWT issuance, and password reset**.
   - It also produces Kafka events, which implies auth-related lifecycle changes can trigger downstream async work.
   - It includes test coverage for both **unit** and **integration** paths, indicating it is one of the more heavily verified services.

6. **User service**
   - The user service owns **candidate profiles, subscriptions, and job applications**.
   - It has auth middleware and Redis/buffer utilities, which suggests it handles protected user data and possibly cached reads or file/image handling.
   - This is the main persistence boundary for candidate-facing data after auth.

7. **Job service**
   - The job service owns **companies and job posting lifecycle**.
   - It also has auth middleware and a Kafka producer, so job-related changes can emit events to the async pipeline.
   - This service appears to be the recruiter-facing domain core.

8. **Payment service**
   - The payment service handles **Razorpay integration** and **subscription activation**.
   - It is isolated as its own service, which is important because payment/webhook logic usually needs tighter operational and security boundaries than ordinary CRUD APIs.
   - Its main role is to convert payment outcomes into subscription state changes.

9. **Utils service as async worker**
   - The utils service is an **event consumer**, not a request-driven API in the same sense as the domain services.
   - It consumes Kafka events and performs background work such as **email delivery**, **AI resume analysis**, **career guidance generation**, and **file/storage-related processing**.
   - External integrations here are materially important: **Gemini API**, **Nodemailer**, and **Cloudinary** are part of the async processing chain.

10. **Event-driven boundary**
   - Kafka is the main decoupling mechanism between the transactional services and the background worker.
   - Auth, Job, and User produce events; Utils consumes them later to avoid blocking user-facing requests.
   - This gives the architecture a clear split between **synchronous request/response APIs** and **asynchronous side effects**.

11. **State and infrastructure**
   - The services are TypeScript/Express applications that use **PostgreSQL** for durable domain storage.
   - **Redis** is used in two distinct ways: gateway rate limiting and service-side caching.
   - **Kafka** is the event backbone connecting business services to the background processor.

12. **Security and identity flow**
   - Identity is established at the gateway with **JWT verification**, and downstream services rely on forwarded context rather than redoing the full auth check everywhere.
   - Role-based access is part of the token model, supporting recruiter/candidate distinctions across services.
   - This keeps auth concerns centralized while preserving service-level ownership of domain logic.

13. **Deployment and operational model**
   - Every backend service and the frontend are containerized with **Docker**.
   - CI/CD is automated through **GitHub Actions**, which builds images, pushes to **Docker Hub**, and deploys to **AWS EC2**.
   - The deployment model is therefore container-based, service-oriented, and designed for independent restart/upgrade of each component.

14. **How to draw the architecture**
   - A good diagram should show: **Users/Browsers → Frontend → Gateway → {Auth, User, Job, Payment} → PostgreSQL/Redis**, plus **Kafka → Utils** for async processing.
   - External arrows should also connect **Payment ↔ Razorpay**, **Utils ↔ Gemini/Nodemailer/Cloudinary**, and the backend deployment to **Docker Hub/AWS EC2**.
   - The key architectural boundary is that the gateway handles edge concerns, domain services own business state, and utils performs event-driven background work.

Main entry points: [`backend/gateway/src/app.ts`](https://github.com/arunkoo/jobvyn/blob/main/backend/gateway/src/app.ts) (Gateway), [`backend/utils/src/consumer.ts`](https://github.com/arunkoo/jobvyn/blob/main/backend/utils/src/consumer.ts) (Utils), [`backend/auth/src/app.ts`](https://github.com/arunkoo/jobvyn/blob/main/backend/auth/src/app.ts) (Auth), [`backend/user/src/controller/user.ts`](https://github.com/arunkoo/jobvyn/blob/main/backend/user/src/controller/user.ts) (User)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_users(("Users<br/>actors"))
end

subgraph group_frontend["Frontend"]
  node_webapp["Frontend<br/>nextjs app<br/>[layout.tsx]"]
end

subgraph group_backend["Backend"]
  node_gateway["Gateway<br/>[app.ts]"]
  node_authsvc["Auth<br/>[app.ts]"]
  node_usersvc["User<br/>profile service<br/>[user.ts]"]
  node_jobsvc["Job<br/>[job.ts]"]
  node_paymentsvc["Payment<br/>billing service<br/>[payment.ts]"]
  node_utilsvc["Utils<br/>async worker<br/>[consumer.ts]"]
end

subgraph group_data["Data & messaging"]
  node_postgres[("PostgreSQL<br/>relational db")]
  node_redis[("Redis<br/>cache/rate limit<br/>[redis.ts]")]
  node_kafka["Kafka<br/>event bus"]
end

subgraph group_external["External services"]
  node_razorpay(("Razorpay<br/>payment provider"))
  node_gemini(("Gemini<br/>ai api"))
  node_mailer(("Nodemailer<br/>email transport"))
  node_cloudinary(("Cloudinary<br/>media storage"))
end

subgraph group_delivery["Delivery"]
  node_githubactions["CI/CD<br/>github actions<br/>[deploy.yml]"]
  node_dockerhub[("Docker Hub<br/>image registry")]
  node_ec2(("AWS EC2<br/>deployment target"))
end

node_users -->|"browse/use"| node_webapp
node_webapp -->|"api calls"| node_gateway
node_gateway -->|"/auth"| node_authsvc
node_gateway -->|"/user"| node_usersvc
node_gateway -->|"/job"| node_jobsvc
node_gateway -->|"/payment"| node_paymentsvc
node_gateway -->|"rate limit"| node_redis
node_gateway -.->|"request ids"| node_gateway
node_authsvc -->|"store identity"| node_postgres
node_usersvc -->|"store profiles"| node_postgres
node_jobsvc -->|"store jobs"| node_postgres
node_paymentsvc -->|"update subs"| node_postgres
node_authsvc -->|"emit events"| node_kafka
node_jobsvc -->|"emit events"| node_kafka
node_usersvc -->|"emit events"| node_kafka
node_kafka -->|"consume"| node_utilsvc
node_utilsvc -->|"ai work"| node_gemini
node_utilsvc -->|"send mail"| node_mailer
node_utilsvc -->|"media ops"| node_cloudinary
node_paymentsvc -->|"charge/webhooks"| node_razorpay
node_githubactions -->|"push images"| node_dockerhub
node_githubactions -->|"deploy"| node_ec2
node_dockerhub -->|"pull images"| node_ec2

click node_webapp "https://github.com/arunkoo/jobvyn/blob/main/frontend/src/app/layout.tsx"
click node_gateway "https://github.com/arunkoo/jobvyn/blob/main/backend/gateway/src/app.ts"
click node_authsvc "https://github.com/arunkoo/jobvyn/blob/main/backend/auth/src/app.ts"
click node_usersvc "https://github.com/arunkoo/jobvyn/blob/main/backend/user/src/controller/user.ts"
click node_jobsvc "https://github.com/arunkoo/jobvyn/blob/main/backend/job/src/controller/job.ts"
click node_paymentsvc "https://github.com/arunkoo/jobvyn/blob/main/backend/payment/src/controller/payment.ts"
click node_utilsvc "https://github.com/arunkoo/jobvyn/blob/main/backend/utils/src/consumer.ts"
click node_redis "https://github.com/arunkoo/jobvyn/blob/main/backend/gateway/src/config/redis.ts"
click node_githubactions "https://github.com/arunkoo/jobvyn/blob/main/.github/workflows/deploy.yml"

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_users toneBlue
class node_webapp toneAmber
class node_gateway,node_authsvc,node_usersvc,node_jobsvc,node_paymentsvc,node_utilsvc toneMint
class node_postgres,node_redis,node_kafka toneRose
class node_razorpay,node_gemini,node_mailer,node_cloudinary toneIndigo
class node_githubactions,node_dockerhub,node_ec2 toneTeal
```

## Components

### Clients

End-user entry points

- **Users**: actors · Browser or mobile users starting platform flows

### Frontend

Next.js UI layer

- [Frontend](https://github.com/arunkoo/jobvyn/blob/main/frontend/src/app/layout.tsx): nextjs app · Next.js App Router UI with auth, jobs, account, subscribe, reset, and payment success flows · `frontend/src/app/layout.tsx`

### Backend

Gateway and domain services

- [Gateway](https://github.com/arunkoo/jobvyn/blob/main/backend/gateway/src/app.ts): api gateway · Edge boundary for routing, JWT validation, rate limiting, request IDs, logging, and error shaping · `backend/gateway/src/app.ts`
- [Auth](https://github.com/arunkoo/jobvyn/blob/main/backend/auth/src/app.ts): auth service · Registration, login, JWT issuance, password reset, and auth event production · `backend/auth/src/app.ts`
- [User](https://github.com/arunkoo/jobvyn/blob/main/backend/user/src/controller/user.ts): profile service · Candidate profiles, subscriptions, and job applications · `backend/user/src/controller/user.ts`
- [Job](https://github.com/arunkoo/jobvyn/blob/main/backend/job/src/controller/job.ts): jobs service · Companies and job posting lifecycle · `backend/job/src/controller/job.ts`
- [Payment](https://github.com/arunkoo/jobvyn/blob/main/backend/payment/src/controller/payment.ts): billing service · Razorpay integration and subscription activation · `backend/payment/src/controller/payment.ts`
- [Utils](https://github.com/arunkoo/jobvyn/blob/main/backend/utils/src/consumer.ts): async worker · Kafka consumer for email, AI resume analysis, career guidance, and storage-related processing · `backend/utils/src/consumer.ts`

### Data & messaging

Shared storage and async backbone

- **PostgreSQL**: relational db · Durable domain storage for transactional services
- [Redis](https://github.com/arunkoo/jobvyn/blob/main/backend/gateway/src/config/redis.ts): cache/rate limit · Gateway rate limiting and service-side caching · `backend/gateway/src/config/redis.ts`
- **Kafka**: event bus · Event backbone linking services to background processing

### External services

Third-party integrations

- **Razorpay**: payment provider · External payment processing and webhook source
- **Gemini**: ai api · AI assistance for resume analysis and career guidance
- **Nodemailer**: email transport · Email delivery used by async workflows
- **Cloudinary**: media storage · File and asset handling for background processing

### Delivery

Build and deployment

- [CI/CD](https://github.com/arunkoo/jobvyn/blob/main/.github/workflows/deploy.yml): github actions · Builds container images and deploys them · `.github/workflows/deploy.yml`
- **Docker Hub**: image registry · Container image registry used during deployment
- **AWS EC2**: deployment target · Container host for the frontend and backend services

## Connections

- Users → Frontend: browse/use · Users start platform flows in the Next.js UI
- Frontend → Gateway: api calls · Frontend sends domain requests to the edge gateway
- Gateway → Auth: /auth · Routes authentication traffic to the auth service
- Gateway → User: /user · Routes profile and application traffic to the user service
- Gateway → Job: /job · Routes company and job traffic to the job service
- Gateway → Payment: /payment · Routes billing and subscription traffic to the payment service
- Gateway → Redis: rate limit · Uses Redis for request throttling and edge state
- Gateway → Gateway: request ids · Adds traceability and shaped error handling at the edge
- Auth → PostgreSQL: store identity · Persists credentials and auth-related state
- User → PostgreSQL: store profiles · Persists candidate data, subscriptions, and applications
- Job → PostgreSQL: store jobs · Persists companies and job postings
- Payment → PostgreSQL: update subs · Persists payment outcomes and subscription activation
- Auth → Kafka: emit events · Publishes auth lifecycle events for downstream processing
- Job → Kafka: emit events · Publishes job-domain events for async consumers
- User → Kafka: emit events · Publishes user-domain events for async consumers
- Kafka → Utils: consume · Background worker consumes business events
- Utils → Gemini: ai work · Calls AI services for resume analysis and guidance
- Utils → Nodemailer: send mail · Delivers transactional and notification email
- Utils → Cloudinary: media ops · Handles storage and asset-processing workflows
- Payment → Razorpay: charge/webhooks · Integrates with the payment provider
- CI/CD → Docker Hub: push images · CI builds and publishes container images
- CI/CD → AWS EC2: deploy · Deploys containerized services to AWS EC2
- Docker Hub → AWS EC2: pull images · EC2 hosts deployed images from the registry
