Skip to content

Commit fa72f86

Browse files
KrunalValviKrunalValvi
committed
refactor: clean up README, add architecture docs, and create demo assets
- Remove 60+ lines of duplicate content from README - Add comprehensive ARCHITECTURE.md with system design and diagrams - Create /assets/demo/ directory with DEMO.md guide - Add links to additional documentation in README - Improve project discoverability and maintainability
1 parent f34aea1 commit fa72f86

File tree

5 files changed

+565
-148
lines changed

5 files changed

+565
-148
lines changed

‎.gitattributes‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Auto detect text files and perform LF normalization
2+
* text=auto eol=lf
3+
4+
# Declare text files
5+
*.py text diff=python
6+
*.md text
7+
*.txt text
8+
*.json text
9+
*.yaml text
10+
*.yml text
11+
*.html text
12+
*.css text
13+
*.js text
14+
*.sh text eol=lf
15+
Dockerfile* text eol=lf
16+
*.toml text
17+
*.ini text
18+
*.sql text
19+
20+
# Binary files
21+
*.png binary
22+
*.jpg binary
23+
*.jpeg binary
24+
*.gif binary
25+
*.ico binary
26+
*.pdf binary
27+
*.zip binary
28+
*.gz binary
29+
*.tar binary
30+
*.pyc binary
31+
*.pyo binary
32+
*.pyd binary
33+
*.so binary
34+
*.dll binary
35+
*.dylib binary

‎ARCHITECTURE.md‎

Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
# Architecture Overview
2+
3+
## System Design
4+
5+
Dev API Vault is built as a **modular FastAPI microservice** designed for scalability, maintainability, and ease of deployment.
6+
7+
```
8+
┌─────────────────────────────────────────────────────────────┐
9+
│ Client Applications │
10+
│ (Web, Mobile, CLI, Third-party APIs) │
11+
└────────────────────────┬────────────────────────────────────┘
12+
│ HTTP/REST
13+
▼
14+
┌─────────────────────────────────────────────────────────────┐
15+
│ FastAPI Application │
16+
│ ┌──────────────────────────────────────────────────────┐ │
17+
│ │ Middleware Layer │ │
18+
│ │ • CORS Middleware (Cross-Origin Resource Sharing) │ │
19+
│ │ • Rate Limiting Middleware │ │
20+
│ │ • Request/Response Logging │ │
21+
│ │ • Security Headers (TrustedHost) │ │
22+
│ └──────────────────────────────────────────────────────┘ │
23+
│ │ │
24+
│ ┌──────────────────────▼──────────────────────────────┐ │
25+
│ │ Router Layer (routers.py) │ │
26+
│ │ • /api/v1/markdown-to-html │ │
27+
│ │ • /api/v1/qr-code │ │
28+
│ │ • /api/v1/image-to-base64 │ │
29+
│ │ • /api/v1/regex-tester │ │
30+
│ │ • /api/v1/word-count │ │
31+
│ │ • /api/v1/summarize │ │
32+
│ └──────────────────────┬──────────────────────────────┘ │
33+
│ │ │
34+
│ ┌──────────────────────▼──────────────────────────────┐ │
35+
│ │ Business Logic Layer (utils.py) │ │
36+
│ │ • Markdown Processing │ │
37+
│ │ • QR Code Generation │ │
38+
│ │ • Image Encoding │ │
39+
│ │ • Regex Validation │ │
40+
│ │ • Web Scraping & Analysis │ │
41+
│ │ • Text Summarization (NLTK) │ │
42+
│ └──────────────────────┬──────────────────────────────┘ │
43+
│ │ │
44+
│ ┌──────────────────────▼──────────────────────────────┐ │
45+
│ │ Data Validation Layer (models.py) │ │
46+
│ │ • Pydantic Request Models │ │
47+
│ │ • Pydantic Response Models │ │
48+
│ │ • Type Hints & Validation │ │
49+
│ └──────────────────────────────────────────────────────┘ │
50+
└─────────────────────────────────────────────────────────────┘
51+
```
52+
53+
## Directory Structure
54+
55+
```
56+
Dev_Api_Vault/
57+
├── app/ # Main application package
58+
│ ├── __init__.py # Package initialization & version
59+
│ ├── main.py # FastAPI app setup & lifespan
60+
│ ├── config.py # Configuration management (settings)
61+
│ ├── models.py # Pydantic request/response models
62+
│ ├── routers.py # API endpoint definitions
63+
│ ├── utils.py # Business logic & utility functions
64+
│ ├── security.py # Authentication & security utilities
65+
│ ├── middleware.py # Custom middleware (rate limiting, etc.)
66+
│ └── openapi.py # OpenAPI/Swagger customization
67+
│
68+
├── tests/ # Test suite
69+
│ ├── __init__.py
70+
│ ├── conftest.py # Pytest configuration & fixtures
71+
│ ├── test_api.py # API endpoint tests
72+
│ └── test_edge_cases.py # Edge case & error handling tests
73+
│
74+
├── assets/ # Static assets
75+
│ └── demo/ # Demo screenshots & documentation
76+
│
77+
├── static/ # Static files (if needed)
78+
│
79+
├── .github/ # GitHub configuration
80+
│ └── workflows/ # CI/CD workflows
81+
│
82+
├── .env.example # Example environment variables
83+
├── .gitignore # Git ignore patterns
84+
├── .gitattributes # Git attributes (line endings)
85+
├── CHANGELOG.md # Version history
86+
├── CONTRIBUTING.md # Contribution guidelines
87+
├── CODE_OF_CONDUCT.md # Community code of conduct
88+
├── DEVELOPMENT.md # Development setup guide
89+
├── LICENSE # MIT License
90+
├── README.md # Project documentation
91+
├── ARCHITECTURE.md # This file
92+
├── Dockerfile # Docker image configuration
93+
├── docker-compose.yml # Multi-container setup
94+
├── pyproject.toml # Poetry project configuration
95+
├── requirements.txt # Pip dependencies
96+
└── build.sh # Build script for NLTK data
97+
```
98+
99+
## Data Flow
100+
101+
### Request Processing Pipeline
102+
103+
```
104+
1. Client Request
105+
↓
106+
2. Middleware Processing
107+
• CORS validation
108+
• Rate limit check
109+
• Request logging
110+
↓
111+
3. Router Matching
112+
• Path matching
113+
• HTTP method validation
114+
↓
115+
4. Request Validation
116+
• Pydantic model validation
117+
• Type checking
118+
↓
119+
5. Business Logic Execution
120+
• Utility function processing
121+
• External API calls (if needed)
122+
↓
123+
6. Response Formatting
124+
• Pydantic response model
125+
• JSON serialization
126+
↓
127+
7. Middleware Post-Processing
128+
• Response logging
129+
• Security headers
130+
↓
131+
8. Client Response
132+
```
133+
134+
## Key Components
135+
136+
### 1. **FastAPI Application** (`main.py`)
137+
- Entry point for the application
138+
- Middleware configuration
139+
- Lifespan management (startup/shutdown)
140+
- OpenAPI documentation setup
141+
- Static file serving
142+
143+
### 2. **Configuration Management** (`config.py`)
144+
- Environment variable loading
145+
- Settings validation
146+
- Default values
147+
- Environment-specific configurations
148+
149+
### 3. **Data Models** (`models.py`)
150+
- Request payload schemas
151+
- Response payload schemas
152+
- Pydantic validation rules
153+
- Type hints for IDE support
154+
155+
### 4. **API Routes** (`routers.py`)
156+
- Endpoint definitions
157+
- HTTP method handlers
158+
- Request/response documentation
159+
- Error handling
160+
161+
### 5. **Business Logic** (`utils.py`)
162+
- Core utility implementations
163+
- External library integrations
164+
- Data processing functions
165+
- Helper methods
166+
167+
### 6. **Security** (`security.py`)
168+
- API key validation
169+
- Authentication helpers
170+
- Password hashing utilities
171+
- Token management
172+
173+
### 7. **Middleware** (`middleware.py`)
174+
- Rate limiting implementation
175+
- Request/response logging
176+
- Custom headers
177+
- Error handling middleware
178+
179+
### 8. **OpenAPI Customization** (`openapi.py`)
180+
- Custom API metadata
181+
- Tag definitions
182+
- Operation configurations
183+
- Security scheme definitions
184+
185+
## Technology Stack
186+
187+
| Layer | Technology | Purpose |
188+
|-------|-----------|---------|
189+
| **Framework** | FastAPI | Modern async web framework |
190+
| **Server** | Uvicorn | ASGI application server |
191+
| **Validation** | Pydantic | Data validation & serialization |
192+
| **Markdown** | markdown | Markdown to HTML conversion |
193+
| **QR Codes** | qrcode + Pillow | QR code generation |
194+
| **Web Scraping** | BeautifulSoup4 + requests | HTML parsing & HTTP requests |
195+
| **Text Processing** | NLTK | Natural language processing |
196+
| **Testing** | Pytest | Unit & integration testing |
197+
| **Code Quality** | Black, isort, Flake8, mypy | Linting & formatting |
198+
| **Containerization** | Docker | Application containerization |
199+
| **CI/CD** | GitHub Actions | Automated testing & deployment |
200+
201+
## Deployment Architecture
202+
203+
### Local Development
204+
```
205+
Developer Machine
206+
├── Python venv
207+
├── FastAPI app (uvicorn)
208+
├── SQLite (optional)
209+
└── NLTK data cache
210+
```
211+
212+
### Docker Deployment
213+
```
214+
Docker Container
215+
├── Python 3.9+ runtime
216+
├── FastAPI app (uvicorn)
217+
├── All dependencies
218+
└── NLTK data (pre-downloaded)
219+
```
220+
221+
### Cloud Deployment (Render/Heroku)
222+
```
223+
Cloud Platform
224+
├── Container registry
225+
├── Managed Python runtime
226+
├── Auto-scaling
227+
├── Health checks
228+
└── Environment variables
229+
```
230+
231+
## Security Considerations
232+
233+
1. **Input Validation**: All inputs validated via Pydantic models
234+
2. **Rate Limiting**: Middleware prevents abuse
235+
3. **CORS Configuration**: Restricted to allowed origins
236+
4. **Trusted Hosts**: TrustedHostMiddleware prevents header injection
237+
5. **Environment Variables**: Sensitive data in `.env` files
238+
6. **Error Handling**: Generic error messages to prevent information leakage
239+
7. **Logging**: Comprehensive logging without sensitive data
240+
241+
## Performance Optimization
242+
243+
1. **Async/Await**: Non-blocking I/O operations
244+
2. **Caching**: Response caching where applicable
245+
3. **Connection Pooling**: Reused HTTP connections
246+
4. **NLTK Data**: Pre-downloaded to avoid runtime downloads
247+
5. **Static File Serving**: Efficient static file delivery
248+
249+
## Scalability
250+
251+
- **Horizontal Scaling**: Stateless design allows multiple instances
252+
- **Load Balancing**: Can be deployed behind a load balancer
253+
- **Database Ready**: Can integrate with PostgreSQL/MongoDB
254+
- **Microservice Ready**: Can be split into separate services
255+
256+
## Future Enhancements
257+
258+
- [ ] Database integration (PostgreSQL/MongoDB)
259+
- [ ] Caching layer (Redis)
260+
- [ ] Message queue (Celery/RabbitMQ)
261+
- [ ] WebSocket support for real-time operations
262+
- [ ] GraphQL endpoint
263+
- [ ] Advanced authentication (OAuth2/JWT)
264+
- [ ] API versioning strategy
265+
- [ ] Monitoring & observability (Prometheus/Grafana)
266+
267+
---
268+
269+
**Last Updated**: 2025-12-01
270+
**Version**: 1.0.0

‎CHANGELOG.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Changelog
2+
3+
All notable changes to the Dev API Vault project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
### Added
10+
- Comprehensive test suite with edge case coverage
11+
- Enhanced API documentation with OpenAPI/Swagger
12+
- Rate limiting middleware for API protection
13+
- CI/CD pipeline with GitHub Actions
14+
- Project configuration with pyproject.toml
15+
- Improved error handling and validation
16+
- Detailed README with setup instructions
17+
- Docker support for containerization
18+
- Code quality tools (Black, isort, Flake8, mypy)
19+
- Security headers and CORS configuration
20+
- Health check endpoints
21+
22+
## [1.0.0] - 2025-12-01
23+
### Added
24+
- Initial release of Dev API Vault
25+
- Core features:
26+
- Markdown to HTML conversion
27+
- QR Code generation
28+
- Image to Base64 conversion
29+
- Regex testing
30+
- Webpage word counting
31+
- Text summarization
32+
- Basic API endpoints
33+
- Basic test coverage
34+
- Initial documentation
35+
36+
[Unreleased]: https://github.com/KrunalValvi/Dev_Api_Vault/compare/v1.0.0...HEAD
37+
[1.0.0]: https://github.com/KrunalValvi/Dev_Api_Vault/releases/tag/v1.0.0

0 commit comments

Comments
 (0)