Bill
8dd4f0ca63
- Bootstrap script for creating monorepo projects - FastAPI backend templates with uv, ruff, mypy, pytest - React frontend templates with TypeScript, ESLint, Prettier - Docker Compose setup with backend, frontend, and database - 9 development and CI scripts - Gitea Actions CI/CD workflows - Comprehensive documentation (8 files) - 45 template files for complete project structure - Automated verification script (all tests pass) - Based on coding-agent-rules standards
132 lines
2.5 KiB
Markdown
132 lines
2.5 KiB
Markdown
# Architecture Documentation
|
|
|
|
## Overview
|
|
|
|
This project follows a monorepo architecture with separate backend and frontend applications.
|
|
|
|
## System Architecture
|
|
|
|
```
|
|
┌─────────────┐
|
|
│ Client │
|
|
│ (Browser) │
|
|
└──────┬──────┘
|
|
│
|
|
│ HTTP/HTTPS
|
|
│
|
|
┌──────▼──────┐
|
|
│ Frontend │
|
|
│ (React) │
|
|
└──────┬──────┘
|
|
│
|
|
│ REST API
|
|
│
|
|
┌──────▼──────┐
|
|
│ Backend │
|
|
│ (FastAPI) │
|
|
└──────┬──────┘
|
|
│
|
|
│ SQL
|
|
│
|
|
┌──────▼──────┐
|
|
│ Database │
|
|
│ (PostgreSQL)│
|
|
└─────────────┘
|
|
```
|
|
|
|
## Backend Architecture
|
|
|
|
### Layers
|
|
|
|
1. **API Layer** (`app/api/`)
|
|
- HTTP endpoints
|
|
- Request/response handling
|
|
- Route definitions
|
|
|
|
2. **Service Layer** (`app/services/`)
|
|
- Business logic
|
|
- Data processing
|
|
- External integrations
|
|
|
|
3. **Data Layer** (`app/db/`)
|
|
- Database models
|
|
- Database connections
|
|
- Query operations
|
|
|
|
4. **Core Layer** (`app/core/`)
|
|
- Configuration
|
|
- Security
|
|
- Error handling
|
|
|
|
### Request Flow
|
|
|
|
```
|
|
Request → API Endpoint → Service → Database → Service → API Response
|
|
```
|
|
|
|
## Frontend Architecture
|
|
|
|
### Structure
|
|
|
|
- **Components** - Reusable UI components
|
|
- **Pages** - Route-level components
|
|
- **Services** - API communication
|
|
- **Store** - State management
|
|
- **Utils** - Helper functions
|
|
|
|
### Data Flow
|
|
|
|
```
|
|
User Action → Component → Service → API → Backend
|
|
↓
|
|
State Update
|
|
↓
|
|
UI Re-render
|
|
```
|
|
|
|
## Deployment Architecture
|
|
|
|
### Development
|
|
|
|
All services run in Docker containers orchestrated by Docker Compose:
|
|
|
|
- Backend container (FastAPI)
|
|
- Frontend container (React dev server)
|
|
- Database container (PostgreSQL)
|
|
|
|
### Production
|
|
|
|
(Add production deployment architecture here)
|
|
|
|
## Security Considerations
|
|
|
|
- CORS configuration
|
|
- Environment variable management
|
|
- API authentication/authorization
|
|
- Input validation
|
|
- SQL injection prevention
|
|
|
|
## Scalability
|
|
|
|
- Horizontal scaling via container orchestration
|
|
- Database connection pooling
|
|
- Caching strategies
|
|
- Load balancing
|
|
|
|
## Technology Stack
|
|
|
|
### Backend
|
|
- Python 3.11+
|
|
- FastAPI
|
|
- Pydantic v2
|
|
- PostgreSQL
|
|
|
|
### Frontend
|
|
- React 18
|
|
- TypeScript
|
|
- Axios
|
|
|
|
### DevOps
|
|
- Docker & Docker Compose
|
|
- Gitea Actions (CI/CD)
|