# Software Architecture Document
## AHABA Journal of Creative Arts (AJCA) Management System

---

## 1. Architecture Overview

The system follows an **MVC-inspired architecture** implemented in Pure PHP 8.2+ with a clear separation between frontend presentation and backend business logic.

```
┌─────────────────────────────────────────────────────────┐
│                   Client Browser                         │
│  HTML5 + Tailwind CSS + Vanilla JS + Alpine.js          │
└────────────────────────┬────────────────────────────────┘
                         │ HTTP/HTTPS
                         ▼
┌─────────────────────────────────────────────────────────┐
│                   Public/index.php                       │
│              (Front Controller - Entry Point)            │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│                   Core/Router.php                        │
│              (Request Routing & Dispatch)                │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│               Middleware Pipeline                        │
│  Auth · CSRF · RBAC · Rate-Limit · Session              │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│              App/Controllers/*.php                       │
│         (Request Handling & Business Logic)              │
└───────┬──────────────────────────────────┬──────────────┘
         │                                  │
         ▼                                  ▼
┌──────────────────┐            ┌─────────────────────────┐
│  App/Models/*.php │            │  App/Services/*.php     │
│  (Data Layer)     │            │  (Business Logic)       │
└───────┬──────────┘            └──────────┬──────────────┘
         │                                  │
         ▼                                  ▼
┌─────────────────────────────────────────────────────────┐
│            Core/Database.php (PDO Layer)                 │
│         Prepared Statements · Transactions               │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│                   MySQL 8+ Database                      │
└─────────────────────────────────────────────────────────┘
```

## 2. Directory Structure

```
ahaba_journals/
├── public/              # Web root (document root)
│   ├── index.php        # Front controller
│   ├── assets/          # Frontend assets (CSS, JS, images)
│   ├── vendor/          # Public vendor libraries
│   └── .htaccess        # Apache URL rewriting
├── app/                 # Application code
│   ├── Controllers/     # Request handlers
│   ├── Models/          # Data access objects
│   ├── Services/        # Business logic services
│   ├── Middleware/      # Request middleware
│   ├── Helpers/         # Utility functions
│   ├── Exceptions/      # Custom exceptions
│   ├── Interfaces/      # Contracts/Interfaces
│   ├── Traits/          # Reusable traits
│   └── Validators/      # Input validation rules
├── core/                # Framework core
│   ├── Application.php  # Application bootstrap
│   ├── Router.php       # Request router
│   ├── Database.php     # PDO database class
│   ├── View.php         # Template engine
│   ├── Session.php      # Session management
│   ├── Security.php     # Security utilities
│   └── ...             # Other core classes
├── config/              # Configuration files
├── database/            # Database migrations & seeds
├── routes/              # Route definitions
├── resources/           # Views, language files, raw assets
│   └── views/           # PHP template files
├── storage/             # Application storage
├── uploads/             # User uploaded files
├── bootstrap/           # Bootstrap script
├── logs/                # Application logs
└── vendor/              # Composer dependencies
```

## 3. Design Patterns

| Pattern | Usage |
|---------|-------|
| MVC | Separation of concerns (Model-View-Controller) |
| Front Controller | Single entry point (public/index.php) |
| Singleton | Database connection, Session |
| Repository | Data access abstraction |
| Factory | Object creation |
| Strategy | Authentication methods |
| Observer | Event/Notification system |
| Middleware | Request filtering pipeline |

## 4. Database Design Principles

- Fully normalized (3NF)
- All tables use InnoDB engine
- Foreign keys with CASCADE/ SET NULL on delete
- Composite indexes on frequently queried columns
- Full-text indexes on searchable columns
- Timestamps (created_at, updated_at) on all entity tables
- Soft deletes where appropriate

## 5. Security Architecture

- **Defense in Depth**: Multiple security layers
- **Input Validation**: Client-side + Server-side validation
- **Output Escaping**: Context-aware escaping (HTML, JS, URL)
- **CSRF**: Token-based protection on all state-changing requests
- **SQL Injection**: PDO prepared statements exclusively
- **XSS**: HTML escaping, Content Security Policy headers
- **Authentication**: bcrypt password hashing, secure sessions
- **Authorization**: RBAC with permission checks on every route
- **File Uploads**: MIME validation, size limits, secure storage
- **Audit Logging**: All state changes recorded

## 6. API Design

The system exposes RESTful JSON endpoints for AJAX interactions:

- `GET /api/articles` - List articles
- `GET /api/articles/{id}` - Article details
- `POST /api/submissions` - Submit manuscript
- `GET /api/reviews` - List reviews
- `POST /api/reviews` - Submit review
- `GET /api/stats` - Dashboard statistics

## 7. Performance Considerations

- Database query optimization with proper indexing
- Lazy loading for images and content
- Browser caching via Cache-Control headers
- Session storage in filesystem (configurable to Redis)
- Minified CSS/JS assets for production
- Pagination on all list views