# ajaysinghratnawat/404-debuggers architecture

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

- Interactive diagram: https://gitdiagram.com/ajaysinghratnawat/404-debuggers
- Repository: https://github.com/ajaysinghratnawat/404-debuggers

## Overview

1. This repository is a small multi-service backend system for a pharmacy domain, with two Java Spring Boot backend variants and one Python AI service. The main architectural split is between the core transactional backend and a separate AI recommendation/search service.

2. The Java backend is organized as a classic layered monolith: HTTP controllers at the edge, service implementations for business logic, Spring Data repositories for persistence, and JPA-style domain entities for the data model. The main package is `com.pharmazone`.

3. The domain model centers on users, medicines, orders, prescriptions, consultations, and platform pricing. The entities and enums suggest workflows for customer ordering, prescription handling, doctor consultations, order status tracking, and role-based access control.

4. The exposed API surface is divided by concern into controllers such as `AuthController`, `MedicineController`, `OrderController`, `PrescriptionController`, and `ConsultationController`. In the v2 backend there is also an `AIController`, which is the integration point for AI-driven features.

5. Business logic lives in service classes under `service/impl`, including `AuthService`, `MedicineService`, `OrderService`, `PrescriptionService`, and `ConsultationService`. In v2, `AIServiceClient` acts as an outbound client to the Python AI service rather than embedding AI logic in the Java app.

6. Persistence is handled through repository interfaces for each aggregate or major entity: user, medicine, order, prescription, consultation, and platform price. This implies the backend reads and writes a relational datastore through the repository layer, with controllers never talking directly to persistence.

7. Security is a first-class boundary in the Java backend. `SecurityConfig`, `JwtAuthFilter`, `JwtUtil`, and `CustomUserDetailsService` indicate stateless JWT-based authentication with role-aware authorization, which is reinforced by the `Role` enum and the authentication DTOs.

8. Cross-cutting concerns are centralized in exception and configuration packages. `GlobalExceptionHandler` and custom exceptions provide consistent API error handling, while `AppConfig` and `RestTemplateConfig` wire infrastructure beans. In v2, `ai.properties` isolates configuration for the AI endpoint.

9. The Python AI service is a separate deployable application under `pharmazone-ai-service/pharmazone-ai`. Its structure resembles a FastAPI app: `app/main.py` is the entry point, `routers/` contains feature endpoints for search, pricing, demand, and substitutes, `models/schemas.py` defines request/response shapes, and `services/model_loader.py` loads the underlying model or scoring assets.

10. The main data flow for AI features is: client calls the Java backend, the backend controller/service invokes `AIServiceClient`, and that client calls the Python service over HTTP. The AI service then returns ranked or generated outputs such as substitute drugs, price insights, demand signals, or search results back to the Java API.

11. The presence of both `pharmazone-backend` and `pharmazone-backend-v2` suggests two versions of the same Spring Boot backend. For architecture diagrams, treat v2 as the evolved version: it contains the same transactional core plus explicit AI integration, while the older backend is the non-AI baseline.

12. Overall, the system boundaries are: API/security at the edge, domain/services in the middle, repositories/database access below, and an external Python AI microservice on the side. The likely deployment shape is a Java Spring Boot API backed by a database, with a separate Python inference service called only for AI-related endpoints.

Main entry points: [`pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/controller`](https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/controller) (Controllers), [`pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/service/impl`](https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/service/impl) (Services), [`pharmazone-backend/pharmazone/src/main/java/com/pharmazone/controller`](https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend/pharmazone/src/main/java/com/pharmazone/controller) (Controllers), [`pharmazone-backend/pharmazone/src/main/java/com/pharmazone/service/impl`](https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend/pharmazone/src/main/java/com/pharmazone/service/impl) (Services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_backend_v1["Backend v1"]
  node_n_v1_app(("Boot app<br/>Spring Boot entry"))
  node_n_v1_config["Config"]
  node_n_v1_controllers["Controllers<br/>HTTP API"]
  node_n_v1_services["Services<br/>business logic"]
  node_n_v1_repos["Repositories<br/>data access"]
  node_n_v1_domain[("Domain model<br/>entities/enums")]
  node_n_v1_security["Security<br/>JWT auth"]
  node_n_v1_errors["Errors<br/>exception handling"]
end

subgraph group_g_backend_v2["Backend v2"]
  node_n_v2_app(("Boot app<br/>Spring Boot entry"))
  node_n_v2_config["Config"]
  node_n_v2_controllers["Controllers<br/>HTTP API"]
  node_n_v2_services["Services<br/>business logic"]
  node_n_v2_repos["Repositories<br/>data access"]
  node_n_v2_domain[("Domain model<br/>entities/enums")]
  node_n_v2_security["Security<br/>JWT auth"]
  node_n_v2_errors["Errors<br/>exception handling"]
end

subgraph group_g_ai_service["AI service"]
  node_n_ai_app(("App<br/>FastAPI entry<br/>[main.py]"))
  node_n_ai_routers["Routers<br/>API routes"]
  node_n_ai_models["Schemas<br/>pydantic models<br/>[schemas.py]"]
  node_n_ai_services["Model loader<br/>inference support<br/>[model_loader.py]"]
end

node_n_v1_app -->|"wires"| node_n_v1_config
node_n_v1_app -->|"starts"| node_n_v1_controllers
node_n_v1_controllers -->|"calls"| node_n_v1_services
node_n_v1_services -->|"persists via"| node_n_v1_repos
node_n_v1_services -->|"operates on"| node_n_v1_domain
node_n_v1_config -->|"configures"| node_n_v1_security
node_n_v1_controllers -->|"handled by"| node_n_v1_errors
node_n_v1_security -->|"uses roles"| node_n_v1_domain
node_n_v2_app -->|"wires"| node_n_v2_config
node_n_v2_app -->|"starts"| node_n_v2_controllers
node_n_v2_controllers -->|"calls"| node_n_v2_services
node_n_v2_services -->|"persists via"| node_n_v2_repos
node_n_v2_services -->|"operates on"| node_n_v2_domain
node_n_v2_config -->|"configures"| node_n_v2_security
node_n_v2_controllers -->|"handled by"| node_n_v2_errors
node_n_v2_services -->|"invokes"| node_n_ai_services
node_n_v2_controllers -->|"via AI endpoints"| node_n_ai_app
node_n_ai_app -->|"mounts"| node_n_ai_routers
node_n_ai_routers -->|"validates with"| node_n_ai_models
node_n_ai_routers -->|"loads"| node_n_ai_services

click node_n_v1_app "https://github.com/ajaysinghratnawat/404-debuggers/blob/main/pharmazone-backend/pharmazone/src/main/java/com/pharmazone/PharmaZoneApplication.java"
click node_n_v1_config "https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend/pharmazone/src/main/java/com/pharmazone/config"
click node_n_v1_controllers "https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend/pharmazone/src/main/java/com/pharmazone/controller"
click node_n_v1_services "https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend/pharmazone/src/main/java/com/pharmazone/service/impl"
click node_n_v1_repos "https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend/pharmazone/src/main/java/com/pharmazone/repository"
click node_n_v1_domain "https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend/pharmazone/src/main/java/com/pharmazone/entity"
click node_n_v1_security "https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend/pharmazone/src/main/java/com/pharmazone/security"
click node_n_v1_errors "https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend/pharmazone/src/main/java/com/pharmazone/exception"
click node_n_v2_app "https://github.com/ajaysinghratnawat/404-debuggers/blob/main/pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/PharmaZoneApplication.java"
click node_n_v2_config "https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/config"
click node_n_v2_controllers "https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/controller"
click node_n_v2_services "https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/service/impl"
click node_n_v2_repos "https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/repository"
click node_n_v2_domain "https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/entity"
click node_n_v2_security "https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/security"
click node_n_v2_errors "https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/exception"
click node_n_ai_app "https://github.com/ajaysinghratnawat/404-debuggers/blob/main/pharmazone-ai-service/pharmazone-ai/app/main.py"
click node_n_ai_routers "https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-ai-service/pharmazone-ai/app/routers"
click node_n_ai_models "https://github.com/ajaysinghratnawat/404-debuggers/blob/main/pharmazone-ai-service/pharmazone-ai/app/models/schemas.py"
click node_n_ai_services "https://github.com/ajaysinghratnawat/404-debuggers/blob/main/pharmazone-ai-service/pharmazone-ai/app/services/model_loader.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_n_v1_app,node_n_v1_config,node_n_v1_controllers,node_n_v1_services,node_n_v1_repos,node_n_v1_domain,node_n_v1_security,node_n_v1_errors toneBlue
class node_n_v2_app,node_n_v2_config,node_n_v2_controllers,node_n_v2_services,node_n_v2_repos,node_n_v2_domain,node_n_v2_security,node_n_v2_errors toneAmber
class node_n_ai_app,node_n_ai_routers,node_n_ai_models,node_n_ai_services toneMint
```

## Components

### Backend v1

Baseline Spring Boot transactional API

- [Boot app](https://github.com/ajaysinghratnawat/404-debuggers/blob/main/pharmazone-backend/pharmazone/src/main/java/com/pharmazone/PharmaZoneApplication.java): Spring Boot entry · Application entrypoint for the baseline backend · `pharmazone-backend/pharmazone/src/main/java/com/pharmazone/PharmaZoneApplication.java`
- [Config](https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend/pharmazone/src/main/java/com/pharmazone/config): Spring config · Core application and security wiring · `pharmazone-backend/pharmazone/src/main/java/com/pharmazone/config`
- [Controllers](https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend/pharmazone/src/main/java/com/pharmazone/controller): HTTP API · Auth, medicine, order, prescription, and consultation endpoints · `pharmazone-backend/pharmazone/src/main/java/com/pharmazone/controller`
- [Services](https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend/pharmazone/src/main/java/com/pharmazone/service/impl): business logic · Transactional orchestration for core pharmacy workflows · `pharmazone-backend/pharmazone/src/main/java/com/pharmazone/service/impl`
- [Repositories](https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend/pharmazone/src/main/java/com/pharmazone/repository): data access · Spring Data persistence interfaces · `pharmazone-backend/pharmazone/src/main/java/com/pharmazone/repository`
- [Domain model](https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend/pharmazone/src/main/java/com/pharmazone/entity): entities/enums · Users, medicines, orders, prescriptions, consultations, roles, and statuses · `pharmazone-backend/pharmazone/src/main/java/com/pharmazone/entity`
- [Security](https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend/pharmazone/src/main/java/com/pharmazone/security): JWT auth · JWT filter, token utility, and user details service · `pharmazone-backend/pharmazone/src/main/java/com/pharmazone/security`
- [Errors](https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend/pharmazone/src/main/java/com/pharmazone/exception): exception handling · Global exception handling and custom API exceptions · `pharmazone-backend/pharmazone/src/main/java/com/pharmazone/exception`

### Backend v2

Evolved Spring Boot API with AI integration

- [Boot app](https://github.com/ajaysinghratnawat/404-debuggers/blob/main/pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/PharmaZoneApplication.java): Spring Boot entry · Application entrypoint for the AI-enabled backend · `pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/PharmaZoneApplication.java`
- [Config](https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/config): Spring config · Application, REST client, security, and AI endpoint configuration · `pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/config`
- [Controllers](https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/controller): HTTP API · Auth, medicine, order, prescription, consultation, and AI endpoints · `pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/controller`
- [Services](https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/service/impl): business logic · Transactional orchestration plus outbound AI client · `pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/service/impl`
- [Repositories](https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/repository): data access · Spring Data persistence interfaces · `pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/repository`
- [Domain model](https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/entity): entities/enums · Users, medicines, orders, prescriptions, consultations, roles, and statuses · `pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/entity`
- [Security](https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/security): JWT auth · JWT filter, token utility, and user details service · `pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/security`
- [Errors](https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/exception): exception handling · Global exception handling and custom API exceptions · `pharmazone-backend-v2/pharmazone/src/main/java/com/pharmazone/exception`

### AI service

Separate Python inference service

- [App](https://github.com/ajaysinghratnawat/404-debuggers/blob/main/pharmazone-ai-service/pharmazone-ai/app/main.py): FastAPI entry · Python service entrypoint · `pharmazone-ai-service/pharmazone-ai/app/main.py`
- [Routers](https://github.com/ajaysinghratnawat/404-debuggers/tree/main/pharmazone-ai-service/pharmazone-ai/app/routers): API routes · Search, price, demand, and substitutes endpoints · `pharmazone-ai-service/pharmazone-ai/app/routers`
- [Schemas](https://github.com/ajaysinghratnawat/404-debuggers/blob/main/pharmazone-ai-service/pharmazone-ai/app/models/schemas.py): pydantic models · Request and response shapes for AI features · `pharmazone-ai-service/pharmazone-ai/app/models/schemas.py`
- [Model loader](https://github.com/ajaysinghratnawat/404-debuggers/blob/main/pharmazone-ai-service/pharmazone-ai/app/services/model_loader.py): inference support · Loads model or scoring assets used by the AI service · `pharmazone-ai-service/pharmazone-ai/app/services/model_loader.py`

## Connections

- Boot app → Config: wires · Bootstraps application configuration and security
- Boot app → Controllers: starts · Exposes the HTTP API
- Controllers → Services: calls · Delegates business operations
- Services → Repositories: persists via · Uses repository interfaces for storage
- Services → Domain model: operates on · Reads and mutates core pharmacy entities
- Config → Security: configures · Sets up JWT-based auth and request filtering
- Controllers → Errors: handled by · API failures flow through global exception handling
- Security → Domain model: uses roles · Authorization depends on user and role model
- Boot app → Config: wires · Bootstraps application configuration and security
- Boot app → Controllers: starts · Exposes the HTTP API
- Controllers → Services: calls · Delegates business operations
- Services → Repositories: persists via · Uses repository interfaces for storage
- Services → Domain model: operates on · Reads and mutates core pharmacy entities
- Config → Security: configures · Sets up JWT-based auth and request filtering
- Controllers → Errors: handled by · API failures flow through global exception handling
- Services → Model loader: invokes · Outbound client calls the Python AI service
- Controllers → App: via AI endpoints · AI features are exposed through the backend API boundary
- App → Routers: mounts · Registers feature routers
- Routers → Schemas: validates with · Uses schemas for request and response contracts
- Routers → Model loader: loads · Routers depend on model-loading support
