Technology Stack - Athena ERP

Overview

Athena ERP is built with a modern, scalable architecture designed for multi-tenant SaaS deployment. The stack prioritizes developer productivity, type safety, and compliance with Colombian regulations.

Frontend Stack

Core Framework

Technology	Version	Purpose
React	19.0.0	UI framework with concurrent features
TypeScript	5.8.2	Type safety and developer experience
Vite	6.2.0	Build tool and dev server
React Router	7.13.1	Client-side routing

State Management & Data Fetching

Zustand

Global state management with persist middleware for auth state

TanStack Query

Server state management, caching, and synchronization

UI & Styling

Tailwind CSS 4.1.14 - Utility-first CSS framework
Motion 12.23.24 - Animation library for smooth transitions
Lucide React 0.546.0 - Icon library
Recharts 3.8.0 - Charts and data visualization
Sonner 2.0.7 - Toast notifications

Form Handling

// React Hook Form + Zod validation pattern
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers';
import { z } from 'zod';

const schema = z.object({
  document_number: z.string().min(6),
  full_name: z.string().min(3),
});

Dependencies:

React Hook Form 7.71.2
Zod 4.3.6
@hookform/resolvers 5.2.2

Authentication

Supabase Auth 2.98.0 - Managed authentication service
JWT tokens with refresh token rotation
Role-based access control (RBAC) enforced in both frontend and backend

HTTP Client

Axios 1.13.6 - HTTP client with interceptors for auth tokens
Base URL configuration via environment variables

Backend Stack

Core Framework

Technology	Version	Purpose
Python	3.12+	Language runtime
FastAPI	0.115+	Modern async web framework
Uvicorn	0.34+	ASGI server with standard extras
Pydantic	2.10+	Data validation and settings

FastAPI automatically generates OpenAPI documentation at /docs (Swagger UI) and /redoc in development mode.

Database Layer

SQLAlchemy 2.0

Async ORM for PostgreSQL with relationship loading and query optimization

Alembic

Database migration management with version control

Key Dependencies:

sqlalchemy[asyncio] 2.0+ - Core ORM with async support
asyncpg 0.30+ - Async PostgreSQL driver
alembic 1.14+ - Migration tool

Authentication & Security

# JWT validation pattern
from python_jose import jwt
from app.auth.permissions import has_permission

def decode_token(token: str) -> TokenPayload:
    payload = jwt.decode(
        token,
        settings.jwt_secret,
        algorithms=[settings.jwt_algorithm]
    )
    return TokenPayload(**payload)

Dependencies:

python-jose[cryptography] 3.3+ - JWT encoding/decoding
httpx 0.28+ - Async HTTP client for Supabase API

File Storage

Cloudflare R2 via boto3 - S3-compatible object storage
boto3 1.35+ - AWS SDK for Python
python-multipart 0.0.20+ - File upload handling

R2 was chosen over S3 for zero egress fees, critical for document-heavy workflows like enrollment.

Performance & Monitoring

Package	Purpose
slowapi 0.1.9+	Rate limiting without Redis
sentry-sdk[fastapi] 2.5+	Error tracking and monitoring

Development Tools

[project.optional-dependencies]
dev = [
    "pytest>=8.3",
    "pytest-asyncio>=0.25",
    "httpx>=0.28",
    "factory-boy>=3.3",
    "ruff>=0.9",
]

Database

PostgreSQL

Supabase PostgreSQL

Managed PostgreSQL with free tier sufficient for 20-40 schools in MVP

Version: PostgreSQL 15+ Key Features Used:

JSONB columns for flexible metadata
Composite indexes for tenant isolation
Foreign key constraints with CASCADE/RESTRICT
Check constraints for data integrity
Async connection pooling (10 connections, 20 max overflow)

Why Not RLS?

Athena intentionally does not use Row Level Security (RLS):

✅ Chosen Approach

Backend middleware enforces tenant isolation
Testable with pytest
Portable to any PostgreSQL
Easier to debug

❌ Not Using RLS

Vendor lock-in to PostgreSQL RLS
Logic split between DB and backend
Harder to test isolation
Difficult to debug leaks

Hosting & Infrastructure

Development

Frontend: Vite dev server (port 3000)
Backend: Uvicorn with hot reload
Database: Local PostgreSQL or Supabase

MVP Deployment

Railway

Backend API hosting with automatic deploys from Git

Supabase

Managed PostgreSQL + Auth in free tier

Cloudflare R2

Document storage (enrollment files, circulars, evidence)

Production Roadmap

For production with real student data, Colombian regulations require:

Database in South America region (GCP southamerica-east1)
Migration from Railway → GCP Cloud Run
Migration from Supabase → GCP Cloud SQL

Type Safety

Frontend ↔ Backend Contract

# CI pipeline generates TypeScript types from OpenAPI spec
npx openapi-typescript http://localhost:8000/openapi.json -o src/api/types.ts

This ensures:

No manual interface duplication
Type errors caught at build time
API changes break the build immediately

Validation Layers

Frontend

Zod schemas validate user input before submission

Backend

Pydantic models validate request payloads

Database

PostgreSQL constraints enforce data integrity

Environment Configuration

Frontend (.env)

VITE_API_URL=http://localhost:8000
VITE_SUPABASE_URL=https://xxx.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbG...

Backend (.env)

# Database
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/athena_db

# Auth
JWT_SECRET=super-secret-key-change-in-prod
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Supabase
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_SERVICE_ROLE_KEY=xxx  # Backend only, never in frontend

# R2
R2_ENDPOINT_URL=https://xxx.r2.cloudflarestorage.com
R2_ACCESS_KEY_ID=xxx
R2_SECRET_ACCESS_KEY=xxx
R2_BUCKET_NAME=athena-docs

# Monitoring
SENTRY_DSN=xxx
ENVIRONMENT=development

Never expose service role keys or secrets in frontend environment variables (no VITE_ prefix).

Overview

Backend

Frontend

Infrastructure

​Overview

​Frontend Stack

​Core Framework

​State Management & Data Fetching

Zustand

TanStack Query

​UI & Styling

​Form Handling

​Authentication

​HTTP Client

​Backend Stack

​Core Framework

​Database Layer

SQLAlchemy 2.0

Alembic

​Authentication & Security

​File Storage

​Performance & Monitoring

​Development Tools

​Database

​PostgreSQL

Supabase PostgreSQL

​Why Not RLS?

✅ Chosen Approach

❌ Not Using RLS

​Hosting & Infrastructure

​Development

​MVP Deployment

​Production Roadmap

​Type Safety

​Frontend ↔ Backend Contract

​Validation Layers

​Environment Configuration

​Frontend (.env)

​Backend (.env)

​Architecture Diagram

​Next Steps

Database Schema

Multi-Tenancy

Build docs developers (and LLMs) love

Overview

Frontend Stack

Core Framework

State Management & Data Fetching

UI & Styling

Form Handling

Authentication

HTTP Client

Backend Stack

Core Framework

Database Layer

Authentication & Security

File Storage

Performance & Monitoring

Development Tools

Database

PostgreSQL

Why Not RLS?

Hosting & Infrastructure

Development

MVP Deployment

Production Roadmap

Type Safety

Frontend ↔ Backend Contract

Validation Layers

Environment Configuration

Frontend (.env)

Backend (.env)

Architecture Diagram

Next Steps