Skip to content

Commit aa920ce

Browse files
netteNznetteNz
committed
cleaned up docs
1 parent 0bda89b commit aa920ce

79 files changed

Lines changed: 37050 additions & 5153 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/deploy-docs.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ name: Deploy Documentation
33
on:
44
push:
55
branches:
6-
- main
6+
- master
77
paths:
88
- 'docs/**'
99
- 'mkdocs.yml'

‎ARCHITECTURE.md‎

Lines changed: 197 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -4,111 +4,245 @@ This document describes the high-level architecture and design decisions for the
44

55
## Architectural Style
66

7-
* **Monolithic web application**
8-
* **Layered architecture** (Servlet → DAO → Database)
9-
* Server-side rendering using **JSP**
7+
The application follows a **monolithic, layered architecture** with server-side rendering:
8+
9+
- **Monolithic web application** - Single deployable WAR file
10+
- **Layered architecture** - Clear separation between presentation, business logic, and data access
11+
- **Server-side rendering** - JSP for dynamic HTML generation
12+
13+
## System Diagram
1014

1115
```
12-
Browser
13-
↓ HTTP
14-
Servlets (Controllers)
15-
↓
16-
DAO Layer (JDBC)
17-
↓
18-
MySQL Database
16+
┌─────────────────────────────────────────────┐
17+
│ Browser (Client) │
18+
└─────────────────┬───────────────────────────┘
19+
│ HTTP
20+
↓
21+
┌─────────────────────────────────────────────┐
22+
│ Servlet Container (Tomcat) │
23+
│ ┌────────────────────────────────────────┐ │
24+
│ │ Filters (Auth, CORS, etc.) │ │
25+
│ └──────────────┬─────────────────────────┘ │
26+
│ ↓ │
27+
│ ┌────────────────────────────────────────┐ │
28+
│ │ Servlets (Controllers) │ │
29+
│ │ - LoginServlet │ │
30+
│ │ - CreateProductServlet │ │
31+
│ │ - BidServlet │ │
32+
│ │ - AdminDashboardServlet │ │
33+
│ └──────────────┬─────────────────────────┘ │
34+
│ ↓ │
35+
│ ┌────────────────────────────────────────┐ │
36+
│ │ JSP Views (Presentation) │ │
37+
│ └────────────────────────────────────────┘ │
38+
└─────────────────┬───────────────────────────┘
39+
│ JDBC
40+
↓
41+
┌─────────────────────────────────────────────┐
42+
│ DAO Layer (Data Access Objects) │
43+
│ - UserDao │
44+
│ - ProductDao │
45+
│ - BidDao │
46+
│ - StatsDao │
47+
└─────────────────┬───────────────────────────┘
48+
│ SQL
49+
↓
50+
┌─────────────────────────────────────────────┐
51+
│ MySQL Database │
52+
│ Tables: users, products, departments, bids │
53+
└─────────────────────────────────────────────┘
1954
```
2055

2156
## Layers
2257

2358
### 1. Presentation Layer (JSP)
2459

25-
* JSP views under `WEB-INF/jsp/`
26-
* Responsible for rendering HTML
27-
* No direct database access
60+
Located in `src/main/webapp/WEB-INF/jsp/`
61+
62+
**Responsibilities:**
63+
- Render HTML based on model data
64+
- Display forms and user interfaces
65+
- No business logic or direct database access
66+
67+
**Key Views:**
68+
- `auth/login.jsp`, `auth/register.jsp`
69+
- `product/create.jsp`, `product/list.jsp`
70+
- `admin/dashboard.jsp`, `admin/users.jsp`
2871

2972
### 2. Controller Layer (Servlets)
3073

31-
* Handles HTTP requests and responses
32-
* Performs validation and authorization checks
33-
* Delegates persistence to DAO classes
74+
Located in `src/main/java/com/nettenz/ebay/servlet/`
3475

35-
Examples:
76+
**Responsibilities:**
77+
- Handle HTTP requests and responses
78+
- Perform validation and authorization checks
79+
- Orchestrate business logic
80+
- Delegate persistence to DAO classes
81+
- Forward to appropriate JSP views
3682

37-
* `LoginServlet`
38-
* `CreateProductServlet`
39-
* `AdminDashboardServlet`
83+
**Examples:**
84+
- `LoginServlet` - Handles authentication
85+
- `CreateProductServlet` - Product creation logic
86+
- `BidServlet` - Bidding operations
87+
- `AdminDashboardServlet` - Admin statistics
4088

4189
### 3. Filter Layer
4290

43-
* Cross-cutting concerns
44-
* Authentication and role-based authorization
45-
* Protects admin and authenticated routes
91+
Located in `src/main/java/com/nettenz/ebay/filter/`
4692

47-
Key component:
93+
**Responsibilities:**
94+
- Cross-cutting concerns (authentication, logging, CORS)
95+
- Intercept requests before they reach servlets
96+
- Enforce security policies
4897

49-
* `AuthFilter`
98+
**Key Component:**
99+
- `AuthFilter` - Session validation and role-based authorization
50100

51101
### 4. Data Access Layer (DAO)
52102

53-
* Encapsulates all SQL logic
54-
* Uses JDBC with PreparedStatements
55-
* Prevents SQL injection and isolates persistence
103+
Located in `src/main/java/com/nettenz/ebay/dao/`
56104

57-
Examples:
105+
**Responsibilities:**
106+
- Encapsulate all SQL logic
107+
- Use JDBC with PreparedStatements
108+
- Prevent SQL injection
109+
- Provide clean API for data operations
58110

59-
* `UserDao`
60-
* `ProductDao`
61-
* `StatsDao`
111+
**Examples:**
112+
- `UserDao` - User CRUD operations
113+
- `ProductDao` - Product management
114+
- `BidDao` - Bidding operations
115+
- `StatsDao` - Dashboard statistics
62116

63117
### 5. Database Layer
64118

65-
* MySQL 8.x
66-
* Relational schema with foreign keys
67-
* Core tables: users, products, departments, bids
119+
**Technology:** MySQL 8.x
120+
121+
**Core Tables:**
122+
- `users` - User accounts with roles
123+
- `products` - Auction listings
124+
- `departments` - Product categories
125+
- `bids` - Bid history and tracking
126+
127+
See `db/schema.sql` for details.
68128

69129
## Authentication Flow
70130

131+
```mermaid
132+
sequenceDiagram
133+
User->>+LoginServlet: POST credentials
134+
LoginServlet->>+UserDao: findByUsername()
135+
UserDao->>+MySQL: SELECT user
136+
MySQL-->>-UserDao: User record
137+
UserDao-->>-LoginServlet: User object
138+
LoginServlet->>LoginServlet: BCrypt.verify(password)
139+
LoginServlet->>Session: Store user object
140+
LoginServlet-->>-User: Redirect to dashboard
141+
142+
User->>+ProductServlet: GET /products
143+
ProductServlet->>AuthFilter: Check session
144+
AuthFilter->>Session: Get user
145+
AuthFilter-->>ProductServlet: Authorized
146+
ProductServlet-->>-User: Display products
147+
```
148+
71149
1. User submits credentials
72-
2. Password verified via BCrypt
73-
3. User object stored in HTTP session
74-
4. `AuthFilter` enforces access rules
150+
2. `LoginServlet` queries database via `UserDao`
151+
3. Password verified via BCrypt
152+
4. User object stored in HTTP session
153+
5. Subsequent requests checked by `AuthFilter`
154+
6. Role-based access enforced (USER vs ADMIN)
75155

76156
## Image Handling
77157

78-
* Multipart uploads stored on disk (`uploads/`)
79-
* Images served through `ImageServlet`
80-
* Supports external image URLs as fallback
158+
**Upload Flow:**
159+
1. Multipart form data received by `CreateProductServlet`
160+
2. Files stored on disk in `uploads/` directory
161+
3. Image path saved to database
162+
4. Images served through `ImageServlet`
163+
164+
**External URLs:**
165+
- Supports external image URLs as fallback
166+
- Validated before storage
81167

82-
## Bidding Engine (Planned)
168+
## Bidding Engine
83169

84-
* `BidDao` for bid persistence and queries
85-
* `BidServlet` for bid placement
86-
* Transaction-safe highest-bid validation
87-
* UI updates to show live bid state
170+
**Current Implementation:**
171+
- `BidDao` for bid persistence and queries
172+
- `BidServlet` for bid placement
173+
- Highest bid tracking per product
174+
- Bid history display
88175

89-
## Security Considerations
176+
**Planned Enhancements:**
177+
- Transaction-safe bid validation
178+
- Concurrent bid handling
179+
- Bid increment rules
180+
- Reserve pricing
181+
- Auto-close on auction end
90182

91-
* BCrypt password hashing (12 rounds)
92-
* PreparedStatements for all queries
93-
* Session-based authentication
183+
## Security Architecture
184+
185+
### Current Implementation
186+
187+
✅ **Password Security**
188+
- BCrypt hashing with 12 rounds
189+
- Salted and stored securely
190+
191+
✅ **SQL Injection Prevention**
192+
- PreparedStatements for all queries
193+
- No string concatenation in SQL
194+
195+
✅ **Session Management**
196+
- HTTP sessions for authentication state
197+
- Role-based access control
94198

95199
### Planned Improvements
96200

97-
* CSRF tokens
98-
* HTTPS enforcement
99-
* Input sanitization (XSS)
100-
* Rate limiting on auth endpoints
101-
* Audit logging for admin actions
201+
- 🔄 CSRF tokens for state-changing operations
202+
- 🔄 HTTPS enforcement
203+
- 🔄 Input sanitization (XSS prevention)
204+
- 🔄 Rate limiting on auth endpoints
205+
- 🔄 Audit logging for admin actions
206+
207+
See [Security Guide](docs/security.md) for details.
208+
209+
## Deployment Architecture
210+
211+
**Build Process:**
212+
```bash
213+
Maven → JAR dependencies + WAR packaging → Tomcat deployment
214+
```
215+
216+
**Runtime:**
217+
- Apache Tomcat 10.1+ (Servlet Container)
218+
- MySQL 8.x (Database Server)
219+
- File system (Image uploads)
102220

103-
## Deployment
221+
**Configuration:**
222+
- Database credentials (currently hardcoded)
223+
- Upload paths (configurable)
224+
- Session timeout settings
104225

105-
* Built as WAR via Maven
106-
* Deployed to Apache Tomcat 10.1+
107-
* Environment-specific config planned for production
226+
See [Deployment Guide](docs/deployment.md) for production setup.
108227

109228
## Future Evolution
110229

111-
* Auction closing scheduler
112-
* Bid history & product detail pages
113-
* Environment-based configuration
114-
* Possible migration to REST + SPA frontend
230+
### Short-term
231+
- Auction closing scheduler (cron/timer)
232+
- Enhanced bid validation
233+
- Environment-based configuration
234+
235+
### Long-term
236+
- REST API layer
237+
- SPA frontend (React/Vue)
238+
- Microservices architecture
239+
- Cloud deployment (AWS/Azure)
240+
- Real-time bidding with WebSockets
241+
242+
## Design Patterns Used
243+
244+
- **MVC** (Model-View-Controller) - Servlet/JSP separation
245+
- **DAO** (Data Access Object) - Database abstraction
246+
- **Factory** - Database connection management
247+
- **Filter Chain** - Request interception
248+
- **Session Facade** - User state management

0 commit comments

Comments
 (0)