Skip to content

Commit 8a01d15

Browse files
samriddhiyadavsamriddhiyadav
committed
feat: finalize project structure and documentation
0 parents  commit 8a01d15

34 files changed

Lines changed: 9132 additions & 0 deletions

‎.env.example‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
APP_ENV=development
2+
SITE_NAME=Quill
3+
BASE_URL=http://localhost/quill
4+
5+
DB_HOST=127.0.0.1
6+
DB_PORT=3306
7+
DB_NAME=quill
8+
DB_USER=root
9+
DB_PASS=

‎.github/workflows/quality.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: PHP Quality
2+
3+
on:
4+
push:
5+
branches: [ main, master ]
6+
pull_request:
7+
8+
jobs:
9+
lint:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Checkout
13+
uses: actions/checkout@v4
14+
15+
- name: Setup PHP
16+
uses: shivammathur/setup-php@v2
17+
with:
18+
php-version: '8.2'
19+
20+
- name: PHP lint
21+
run: |
22+
find . -type f -name "*.php" -not -path "./vendor/*" -print0 | xargs -0 -n1 php -l

‎.gitignore‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# OS
2+
.DS_Store
3+
Thumbs.db
4+
5+
# IDE
6+
.vscode/
7+
.idea/
8+
*.swp
9+
10+
# Env
11+
.env
12+
.env.local
13+
14+
# Logs
15+
*.log
16+
logs/
17+
18+
# Build artifacts
19+
dist/
20+
build/
21+
coverage/
22+
23+
# Runtime / uploads
24+
uploads/*
25+
!uploads/.gitkeep
26+
storage/

‎CONTRIBUTING.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Contributing
2+
3+
## Development Flow
4+
5+
1. Fork the repository and create a feature branch.
6+
2. Keep changes scoped and include clear commit messages.
7+
3. Update documentation and diagrams for architecture-impacting changes.
8+
4. Run project-specific checks before opening a PR.
9+
10+
## Pull Request Checklist
11+
12+
- [ ] Code compiles/runs locally
13+
- [ ] README/docs updated
14+
- [ ] No secrets committed
15+
- [ ] Screenshots added for UI updates (if applicable)

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Quill - Role-Based Blogging Platform
2+
3+
## Overview
4+
Quill is a PHP + MySQL blogging platform with role-based workflows for **viewer**, **author**, and **admin** users. It demonstrates end-to-end web engineering fundamentals: authentication, content lifecycle management, media handling, and dashboard-oriented operations.
5+
6+
## Problem Statement
7+
Most beginner blog projects only cover basic CRUD and miss role separation, moderation workflows, and operational readiness. Quill addresses this by implementing a multi-role publishing workflow with clean separation between public browsing and protected author/admin operations.
8+
9+
## Solution Overview
10+
Quill uses server-rendered PHP views backed by MySQL (PDO). Authentication and authorization gates users into role-specific modules. Authors create and manage posts, admins oversee users/content, and viewers consume published content.
11+
12+
## Features
13+
- Role-based access control (`viewer`, `author`, `admin`)
14+
- Authentication and session-based authorization
15+
- Author workflows: create, edit, publish/draft posts
16+
- Admin workflows: dashboard and user/content oversight
17+
- Tagging and featured image support
18+
- Public viewer pages for published articles
19+
20+
## Architecture
21+
Application modules are organized by role and shared includes:
22+
- `index.php`: entry and route switching
23+
- `src/auth`: login/auth handling
24+
- `src/author`: author dashboards and post operations
25+
- `src/admin`: admin management dashboards
26+
- `src/viewer`: public content pages
27+
- `includes/config.php`: environment and DB bootstrap
28+
- `includes/functions.php`: shared utilities/data access helpers
29+
30+
## Tech Stack
31+
- PHP 8+
32+
- MySQL 8+ (PDO)
33+
- HTML/CSS/Bootstrap-style UI
34+
- Apache/XAMPP local runtime
35+
36+
## Architecture Diagram
37+
```mermaid
38+
flowchart LR
39+
V[Viewer Browser] --> A[Apache + PHP App]
40+
AU[Author/Admin Browser] --> A
41+
A --> AUTH[Auth + Session Layer]
42+
A --> MOD[Role Modules in src/]
43+
MOD --> DAL[Data Access Helpers]
44+
DAL --> DB[(MySQL)]
45+
MOD --> FS[(uploads/ + assets/)]
46+
```
47+
48+
## Setup Instructions
49+
1. Clone repository into XAMPP htdocs.
50+
2. Copy `.env.example` to `.env` and set DB values.
51+
3. Create database and import `docs/schema.sql`.
52+
4. Start Apache and MySQL from XAMPP.
53+
5. Open `http://localhost/quill`.
54+
55+
## Usage
56+
- Sign in via auth flow.
57+
- Create/edit posts from author dashboard.
58+
- Manage users/content from admin dashboard.
59+
- Review published posts from viewer pages.
60+
61+
## API / Data Layer Notes
62+
Quill is server-rendered and does not expose a standalone REST API. Data operations are centralized in PHP utility functions under `includes/functions.php`.
63+
64+
## Screenshots
65+
- `docs/screenshots/home.png` (placeholder)
66+
- `docs/screenshots/author-dashboard.png` (placeholder)
67+
- `docs/screenshots/admin-dashboard.png` (placeholder)
68+
69+
## Deployment
70+
See `docs/DEPLOYMENT.md` for local and production deployment steps.
71+
72+
## Future Improvements
73+
- CSRF middleware across all state-changing routes
74+
- Form request validation abstraction
75+
- Unit/integration tests for auth and publishing workflows
76+
- Structured logging and audit trails
77+
- Optional REST API for headless clients
78+
79+
## Contributing
80+
See `CONTRIBUTING.md` for development workflow and quality expectations.
81+
82+
## License
83+
MIT

‎architecture/README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Architecture Summary
2+
3+
Quill follows a role-oriented monolith architecture.
4+
5+
## Layers
6+
1. Presentation: PHP-rendered pages in `index.php` and `src/*`.
7+
2. Access Control: session-driven role checks.
8+
3. Business/Data Logic: shared helper functions in `includes/functions.php`.
9+
4. Persistence: MySQL accessed via PDO in `includes/config.php`.
10+
5. Static and upload assets: `assets/`, `uploads/`.
11+
12+
## Tradeoffs
13+
- Simple and fast to iterate for portfolio and small-team projects.
14+
- Limited scalability due to function-centric shared module design.
15+
- Good migration path toward service/repository architecture.

0 commit comments

Comments
 (0)