# 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)