Developer Documentation

Tech Stack

Architecture

splanly follows a server-side rendered (SSR) architecture with FastAPI serving Jinja2 templates for the main application. A separate /api/v1 namespace provides RESTful JSON endpoints designed for consumption by a Next.js frontend (or any SPA/mobile client).

Request Flow

Browser / SPA
    │
    ├─ SSR Pages ──→ FastAPI Routers ──→ Jinja2 Templates ──→ HTML
    │
    └─ API v1 ────→ FastAPI API Routers ──→ JSON Responses
                        │
                        ├──→ Services (business logic)
                        │
                        └──→ SQLAlchemy ORM ──→ PostgreSQL

Key Design Decisions

• Multi-tenant by design — Firm-owned data is scoped to a firm_id. PostgreSQL RLS is enabled on public tables and denies unconfigured PostgREST roles by default.
• SSR first, API second — The primary interface is server-rendered HTML. The API layer (/api/v1) exists for the planned Next.js frontend migration.
• Middleware-driven auth — A session middleware (app/middleware/) handles authentication state across both SSR and API requests.
• Approval workflows — Built-in approval system for leave requests, engagement extensions, and other firm-defined actions.

Project Structure

pm-tool/
├── app/
│   ├── api/
│   │   └── v1/              # REST API endpoints (JSON)
│   │       ├── auth.py          # Auth endpoints (JWT, OAuth)
│   │       ├── clients.py       # Client CRUD
│   │       ├── engagements.py   # Engagement management
│   │       ├── assignments.py   # Assignment operations
│   │       ├── team_members.py  # Team member management
│   │       ├── leaves.py        # Leave management
│   │       ├── dashboard.py     # Dashboard data endpoints
│   │       ├── approval.py      # Approval workflow endpoints
│   │       ├── extensions.py    # Engagement extension requests
│   │       └── deps.py          # Shared dependencies
│   ├── routers/             # SSR page routes (Jinja2)
│   │   ├── auth.py, dashboard.py, clients.py
│   │   ├── engagements.py, assignments.py
│   │   ├── team_members.py, leaves.py
│   │   ├── invitations.py, reports.py
│   │   ├── license.py, admin_settings.py
│   │   └── contact.py, health.py, outbox.py
│   ├── models/              # SQLAlchemy models
│   │   ├── models.py            # Core models
│   │   ├── invitation.py        # Invitation model
│   │   ├── super_admin.py       # Super admin model
│   │   └── firm_business_role.py# Business role model
│   ├── schemas/             # Pydantic validation schemas
│   ├── services/            # Business logic layer
│   ├── middleware/           # Auth middleware, request context
│   ├── templates/           # Jinja2 HTML templates
│   │   ├── auth/, dashboard/, clients/
│   │   ├── engagements/, team_members/
│   │   ├── legal/               # Legal pages (this file's siblings)
│   │   └── docs.html, faq.html
│   ├── static/              # CSS, JS, images
│   ├── main.py                  # FastAPI app entry point
│   ├── config.py                # Settings (pydantic-settings)
│   ├── database.py              # SQLAlchemy engine & session
│   ├── csrf.py, csrf_utils.py   # CSRF protection
│   ├── email_worker.py          # Email sending service
│   ├── flash.py                 # Flash message helpers
│   └── exceptions.py            # Custom exception handlers
├── alembic/                   # Database migrations
├── tests/                     # Pytest test suite
├── requirements.txt
├── run_server.py                # Dev server runner
├── alembic.ini
├── render.yaml                  # Render deployment config
└── .env.example                 # Environment variable template

Data Models

All models inherit from SQLAlchemy's declarative Base and are defined in app/models/models.py (plus supplementary files). Every business entity is scoped to a firm for multi-tenancy.

API v1 Endpoints

The /api/v1 namespace provides JSON REST endpoints for the planned Next.js frontend. All endpoints require JWT authentication unless noted.

Full endpoint documentation with request/response schemas is available in the developer dashboard (internal only).

Authentication

Engagements /api/v1/engagements

Assignments /api/v1/assignments

Team Members /api/v1/team-members

Leaves /api/v1/leaves

Dashboard /api/v1/dashboard

Approvals /api/v1/approvals

Authentication

splanly supports three authentication methods, all accessible through the SSR and API layers:

1. Session-Based (SSR)

Default for server-rendered pages. Upon login, a signed session cookie is set using itsdangerous. The session stores the user_id and firm_id, validated by middleware on every request.

Cookie: staffplan_session=<signed-token>

2. JWT (API)

For API v1 endpoints, authentication uses Bearer tokens generated via PyJWT. Tokens are issued on login and include user_id, firm_id, and an expiry claim.

Authorization: Bearer <jwt-token>

3. OAuth 2.0 (Google)

Users can sign in with Google using Authlib. The flow is handled at /api/v1/auth/oauth/google, which redirects to Google and processes the callback to create or link a user account.

Deployment

splanly is deployed on Render with a Neon PostgreSQL database.

Render Configuration

The render.yaml blueprint configures the web service:

services:
  - type: web
    name: staffplan
    env: python
    buildCommand: pip install -r requirements.txt
    startCommand: alembic upgrade head && uvicorn app.main:app --host 0.0.0.0 --port $PORT

Migrations run automatically on every deploy (alembic upgrade head) before the server starts.

Database

Neon provides a serverless PostgreSQL instance. The DATABASE_URL is injected from Render's linked database resource. Connection pooling is handled at the Neon level.

CI/CD

Render auto-deploys on push to the main branch. Pre-deploy, Alembic runs any pending migrations. There is no separate CI pipeline configured — tests can be run locally with pytest.

Environment Variables

Configuration is managed through environment variables, loaded by pydantic-settings in app/config.py. See .env.example for the full template.

Local Development

Get splanly running locally in a few steps:

Prerequisites

• Python 3.11+
• PostgreSQL (local or remote)
• pip or a virtual environment manager

Setup

# Clone the repository
git clone <repo-url>
cd pm-tool

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate        # Linux/macOS
venv\Scripts\activate           # Windows

# Install dependencies
pip install -r requirements.txt

# Copy environment template and configure
cp .env.example .env
# Edit .env with your DATABASE_URL and SECRET_KEY

# Run database migrations
alembic upgrade head

# Start the development server
python run_server.py

The server starts at http://localhost:8000. API documentation is available via the developer dashboard.

Running Tests

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/test_auth.py