Developer Onboarding: Core Architecture

Welcome to the engineering team. This documentation serves as your authoritative guide to our application architecture, infrastructure, and deployment standards.

Objective: Review this document thoroughly to understand our technical constraints and methodologies before initiating your local environment setup.

1. Core Technology Stack

Symfony (Backend Foundation)

Symfony is our structural backend framework. It dictates how we handle HTTP cycles, database transactions, and dependency management.

  • Routing & Controllers: Mapped via PHP 8 Attributes.
  • Dependency Injection (DI): Heavily utilized. Services are autowired and injected via constructors.
  • Doctrine ORM: Our abstraction layer for PostgreSQL interactions. We strictly use migrations for schema changes.

API Platform (API Layer)

API Platform sits atop Symfony, drastically reducing boilerplate for REST and GraphQL endpoints. It natively supports self-describing API standards like JSON-LD and Hydra.

  • Entity Mapping: We expose resources using the #[ApiResource] attribute.
  • Serialization Groups: Critical for data encapsulation. We define strict read/write groups to prevent over-posting and accidental data exposure.

React-Admin (Frontend)

React-Admin allows us to rapidly build B2B interfaces by mapping API Platform endpoints directly to React components.

  • Data Providers: We use the Hydra data provider (@api-platform/admin) which automatically interprets API Platform's JSON-LD responses.
  • Core Components: UIs are constructed using <List>, <Create>, <Edit>, and contextual form inputs.

2. AI Engineering Stack

For our intelligent services and agentic workflows, we utilize a specialized Python-based stack designed to interface seamlessly with Large Language Models.

Python & Django

Python is our primary language for AI services due to its rich ecosystem. We wrap our AI logic within Django to maintain a robust, MVC-structured backend environment.

Django REST Framework (DRF)

Just as we use API Platform in PHP, we use DRF in Python. DRF allows us to expose our AI agent capabilities as secure, structured RESTful API endpoints that our frontends or microservices can consume.

Google Gen AI SDK

We leverage the Google Gen AI SDK to integrate Gemini models into our applications.

  • Agentic Workflows: We build autonomous agents by defining strict system instructions and supplying the model with external tools (function calling) to fetch context or execute actions.
  • Structured Output: We rely on enforcing JSON schemas on model responses to ensure predictable, programmatic communication between the LLM and DRF.

3. DevSecOps & Infrastructure

Docker & Local Environment

We maintain strict environmental parity. All development is containerized using docker-compose. Do not install dependencies directly on your host machine. Source code is mounted via Docker volumes to ensure real-time synchronization.

Security Constraints

  • Stateless Auth: JWT tokens passed via the Authorization: Bearer header.
  • Secrets: Credentials reside in .env.local (or python .env). Never commit secrets.

CI/CD Pipeline

Pull Requests trigger automated pipelines. We enforce static analysis (PHPStan Level 8 / mypy), linting (PHP CS Fixer, ESLint, ruff), and testing before merging into main is permitted.

4. Starter Projects

To validate your understanding of the stack, choose ONE of the following full-stack projects to build from scratch.

Option 1: Team Task Tracker

Stack: Symfony + API Platform + React-Admin

  • Entities: User, Task, Project.
  • Relations: Users and Projects have Many Tasks.
  • Goal: Implement a dashboard with status filters and reference inputs for assigning tasks to specific users.

Option 2: Internal Asset Library

Stack: Symfony + API Platform + React-Admin

  • Entities: Employee, Asset (Laptops, Phones), Category.
  • Relations: Asset belongs to Category and can be checked out by an Employee.
  • Goal: Build a system mapping hardware check-ins/check-outs, enforcing validation logic on asset status.

Option 3: Employee Directory

Stack: Symfony + API Platform + React-Admin

  • Entities: Employee, Department, OfficeLocation.
  • Relations: Employees belong to a Department and a Location. Employees have a self-referencing relationship (Manager -> Subordinates).
  • Goal: Build an interactive corporate directory with hierarchical data representation.

Option 4: AI Support Agent AI Stack

Stack: Python + Django + DRF + Google Gen AI SDK

  • Objective: Build a RESTful agentic service that answers IT support queries.
  • Architecture: Create a Django app exposing a DRF endpoint (POST /api/chat) that accepts user queries.
  • Agent Logic: Initialize a Gemini model with specific system instructions. Provide it with Python tools (functions) it can call, such as search_kb(query) or check_ticket_status(id).
  • Goal: Successfully parse the user input, allow the model to reason and use tools, and return a structured JSON response to the frontend.

5. Milestones & Delivery

  1. Environment Setup: Initialize your framework of choice via docker-compose. Validate connectivity to the local database.
  2. Backend & API: Construct entities/models, map relations, and expose endpoints. Validate via Swagger/Postman.
  3. Frontend Integration: Scaffold the React-Admin app (or simple React UI for the AI agent) and bind it to your endpoints.
  4. Code Review: Push to a feature branch, submit a PR, and sit down with your Tech Lead to discuss architectural choices.